documonster 0.11.0 → 0.11.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.11.0/dist/iife/documonster.excel.iife.min.js"></script>
+<script src="https://unpkg.com/documonster@0.11.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.11.0/dist/iife/documonster.excel.iife.min.js"></script>
+<script src="https://unpkg.com/documonster@0.11.1/dist/iife/documonster.excel.iife.min.js"></script>
 <script>
   const { Workbook, Cell } = Documonster.Excel;
   const wb = Workbook.create();

package/dist/esm/modules/archive/unzip/parser-core.js

@@ -154,22 +154,14 @@ export function isValidZipRecordSignature(sig) {
             return false;
     }
 }
-function readUint32LEFromBytes(view, offset) {
-    return ((view[offset] |
-        0 |
-        ((view[offset + 1] | 0) << 8) |
-        ((view[offset + 2] | 0) << 16) |
-        ((view[offset + 3] | 0) << 24)) >>>
-        0);
-}
 function readUint16LEFromBytes(view, offset) {
     return (view[offset] | ((view[offset + 1] | 0) << 8)) >>> 0;
 }
 function parseCrxHeaderFast(data) {
     return {
-        version: readUint32LEFromBytes(data, 0),
-        pubKeyLength: readUint32LEFromBytes(data, 4),
-        signatureLength: readUint32LEFromBytes(data, 8)
+        version: readUint32LE(data, 0),
+        pubKeyLength: readUint32LE(data, 4),
+        signatureLength: readUint32LE(data, 8)
     };
 }
 function parseLocalFileHeaderVarsFast(data) {
@@ -179,19 +171,19 @@ function parseLocalFileHeaderVarsFast(data) {
         compressionMethod: readUint16LEFromBytes(data, 4),
         lastModifiedTime: readUint16LEFromBytes(data, 6),
         lastModifiedDate: readUint16LEFromBytes(data, 8),
-        crc32: readUint32LEFromBytes(data, 10),
-        compressedSize: readUint32LEFromBytes(data, 14),
-        uncompressedSize: readUint32LEFromBytes(data, 18),
+        crc32: readUint32LE(data, 10),
+        compressedSize: readUint32LE(data, 14),
+        uncompressedSize: readUint32LE(data, 18),
         fileNameLength: readUint16LEFromBytes(data, 22),
         extraFieldLength: readUint16LEFromBytes(data, 24)
     };
 }
 function parseDataDescriptorVarsFast(data) {
     return {
-        dataDescriptorSignature: readUint32LEFromBytes(data, 0),
-        crc32: readUint32LEFromBytes(data, 4),
-        compressedSize: readUint32LEFromBytes(data, 8),
-        uncompressedSize: readUint32LEFromBytes(data, 12)
+        dataDescriptorSignature: readUint32LE(data, 0),
+        crc32: readUint32LE(data, 4),
+        compressedSize: readUint32LE(data, 8),
+        uncompressedSize: readUint32LE(data, 12)
     };
 }
 export const DEFAULT_PARSE_THRESHOLD_BYTES = 5 * 1024 * 1024;

package/dist/esm/modules/archive/zip-spec/binary.js

@@ -1,72 +1,30 @@
 /**
- * Tiny binary reader for Uint8Array-backed DataView.
- * Shared by ZIP parsers.
+ * ZIP-specific binary helpers.
+ *
+ * The little-endian scalar reader, writer and free functions live in
+ * `@utils/binary` (Layer 0) because ZIP is not the only binary container in this
+ * library — BIFF12 in `excel/` and CFB in `word/` need the same primitives, and
+ * none of those modules may import each other. What stays here is the part that
+ * is genuinely about ZIP: CP437 filename decoding, and the declarative
+ * fixed-width header parser the unzip path is written against.
  */
 import { decodeCp437 } from "../core/text.js";
-import { uint8ArrayToString as decodeUtf8 } from "../../../utils/binary.js";
-export function writeUint32LE(value) {
-    const out = new Uint8Array(4);
-    const view = new DataView(out.buffer);
-    view.setUint32(0, value >>> 0, true);
-    return out;
-}
-export function readUint32LE(data, offset) {
-    const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
-    return view.getUint32(offset, true);
-}
-export class BinaryReader {
-    constructor(data, offset = 0) {
-        this.data = data;
-        this.view = new DataView(data.buffer, data.byteOffset, data.byteLength);
-        this.offset = offset;
-    }
-    get position() {
-        return this.offset;
-    }
-    set position(value) {
-        this.offset = value;
-    }
-    get remaining() {
-        return this.data.length - this.offset;
-    }
-    readUint8() {
-        const value = this.view.getUint8(this.offset);
-        this.offset += 1;
-        return value;
-    }
-    readUint16() {
-        const value = this.view.getUint16(this.offset, true);
-        this.offset += 2;
-        return value;
-    }
-    readUint32() {
-        const value = this.view.getUint32(this.offset, true);
-        this.offset += 4;
-        return value;
-    }
-    readBigUint64() {
-        const value = this.view.getBigUint64(this.offset, true);
-        this.offset += 8;
-        return value;
-    }
-    readBytes(length) {
-        const bytes = this.data.subarray(this.offset, this.offset + length);
-        this.offset += length;
-        return bytes;
+import { BinaryReader as LittleEndianReader, readUint16LE, readUint32LE, uint8ArrayToString as decodeUtf8 } from "../../../utils/binary.js";
+export { readUint16LE, readUint32LE, writeUint16LE, writeUint32LE } from "../../../utils/binary.js";
+/**
+ * Little-endian reader with ZIP's two filename encodings.
+ *
+ * ZIP stores names as CP437 unless the general-purpose UTF-8 flag is set, so the
+ * decode choice belongs to the caller reading the header, not to the reader.
+ */
+export class BinaryReader extends LittleEndianReader {
+    constructor(data, offset = 0, label = "zip stream") {
+        super(data, offset, label);
     }
     readString(length, utf8 = true) {
         const bytes = this.readBytes(length);
         return utf8 ? decodeUtf8(bytes) : decodeCp437(bytes);
     }
-    skip(length) {
-        this.offset += length;
-    }
-    slice(start, end) {
-        return this.data.subarray(start, end);
-    }
-    peekUint32(offset) {
-        return this.view.getUint32(offset, true);
-    }
 }
 // =============================================================================
 // Format-based parsing (legacy-style declarative parser)
@@ -89,24 +47,23 @@ export class BinaryReader {
  */
 export function parseFormatted(buffer, format) {
     const result = {};
-    const view = new DataView(buffer.buffer, buffer.byteOffset, buffer.byteLength);
     let offset = 0;
     for (const [key, size] of format) {
         if (buffer.length >= offset + size) {
             switch (size) {
                 case 1:
-                    result[key] = view.getUint8(offset);
+                    result[key] = buffer[offset];
                     break;
                 case 2:
-                    result[key] = view.getUint16(offset, true);
+                    result[key] = readUint16LE(buffer, offset);
                     break;
                 case 4:
-                    result[key] = view.getUint32(offset, true);
+                    result[key] = readUint32LE(buffer, offset);
                     break;
                 case 8: {
                     // Keep behavior (Number) while avoiding BigInt costs.
-                    const low = view.getUint32(offset, true);
-                    const high = view.getUint32(offset + 4, true);
+                    const low = readUint32LE(buffer, offset);
+                    const high = readUint32LE(buffer, offset + 4);
                     result[key] = high * 0x100000000 + low;
                     break;
                 }

package/dist/esm/modules/csv/parse/async.js

@@ -23,6 +23,14 @@ import { parseCsv } from "./sync.js";
 import { CsvParserStream } from "../stream/parser.js";
 import { isReadableStreamLike, readableStreamToAsyncIterable } from "../../stream/utils.base.js";
 import { toError } from "../../../utils/errors.js";
+/**
+ * Rows buffered for the generator's consumer before the parser is paused.
+ *
+ * Small enough that a slow consumer cannot accumulate the whole input, large enough that a
+ * fast one is never throttled between pulls.
+ */
+const ROW_QUEUE_HIGH_WATER_MARK = 1024;
+const ROW_QUEUE_LOW_WATER_MARK = 256;
 function isAsyncIterable(value) {
     return Boolean(value &&
         typeof value[Symbol.asyncIterator] === "function");
@@ -148,6 +156,7 @@ export async function* parseCsvRows(input, options = {}) {
     let ended = false;
     let streamError = null;
     let aborted = false;
+    let paused = false;
     const pushEvent = (ev) => {
         if (pendingResolve) {
             const resolve = pendingResolve;
@@ -157,8 +166,25 @@ export async function* parseCsvRows(input, options = {}) {
         }
         queue.push(ev);
     };
+    // A `data` listener puts the parser in flowing mode, so without this the parser would read
+    // the whole input into `queue` no matter how slowly the consumer of this generator pulls.
+    // Pausing hands that backpressure through to the writer loop below, which already waits for
+    // `drain`.
+    const applyBackpressure = () => {
+        if (!paused && queue.length >= ROW_QUEUE_HIGH_WATER_MARK) {
+            paused = true;
+            parser.pause();
+        }
+    };
+    const releaseBackpressure = () => {
+        if (paused && queue.length <= ROW_QUEUE_LOW_WATER_MARK) {
+            paused = false;
+            parser.resume();
+        }
+    };
     const onData = (value) => {
         pushEvent({ type: "data", value });
+        applyBackpressure();
     };
     const onEnd = () => {
         ended = true;
@@ -202,6 +228,7 @@ export async function* parseCsvRows(input, options = {}) {
         while (true) {
             if (queue.length > 0) {
                 const ev = queue.shift();
+                releaseBackpressure();
                 if (ev.type === "data") {
                     yield ev.value;
                     continue;
@@ -234,6 +261,11 @@ export async function* parseCsvRows(input, options = {}) {
     }
     finally {
         aborted = true;
+        if (paused) {
+            // Let the writer loop finish rather than leaving it blocked behind a paused parser.
+            paused = false;
+            parser.resume();
+        }
         // Ensure stream stops as soon as possible.
         parser.destroy();
         // Release the writer if it is waiting for drain (destroy does not emit drain).

package/dist/esm/modules/csv/parse/config.js

@@ -5,9 +5,9 @@
  * normalized parsing configuration from user options.
  */
 import { DEFAULT_LINEBREAK_REGEX } from "../constants.js";
-import { CsvError } from "../errors.js";
+import { detectDelimiterFor } from "./delimiter-detector.js";
 import { createOnSkipHandler } from "./helpers.js";
-import { normalizeQuoteOption, normalizeEscapeOption, detectDelimiter, detectLinebreak, stripBom } from "../utils/detect.js";
+import { applyFirstChunkPreprocessing, normalizeQuoteOption, normalizeEscapeOption, detectLinebreak } from "../utils/detect.js";
 // =============================================================================
 // Configuration Factory
 // =============================================================================
@@ -38,25 +38,19 @@ export function createParseConfig(opts) {
     let processedInput;
     if (input !== undefined) {
         processedInput = input;
-        // Apply beforeFirstChunk if provided
-        if (beforeFirstChunk) {
-            const result = beforeFirstChunk(processedInput);
-            if (typeof result === "string") {
-                processedInput = result;
-            }
-            else if (result !== undefined && result !== null) {
-                // Validate return type - must be string or void/undefined
-                throw new CsvError(`beforeFirstChunk must return a string or undefined, got ${typeof result}`);
-            }
-        }
-        // Strip BOM
-        processedInput = stripBom(processedInput);
+        processedInput = applyFirstChunkPreprocessing(processedInput, beforeFirstChunk);
     }
     const shouldSkipEmpty = skipEmptyLines;
     // Normalize quote/escape
     const { enabled: quoteEnabled, char: quote } = normalizeQuoteOption(quoteOption);
     const escapeNormalized = normalizeEscapeOption(escapeOption, quote);
     const escape = escapeNormalized.enabled ? escapeNormalized.char || quote : "";
+    // Determine linebreak
+    const linebreak = lineEndingOption || (processedInput !== undefined ? detectLinebreak(processedInput) : "\n");
+    // Pre-compile linebreak regex for fast mode
+    const linebreakRegex = linebreak && linebreak !== "\n" && linebreak !== "\r\n" && linebreak !== "\r"
+        ? linebreak
+        : DEFAULT_LINEBREAK_REGEX;
     // Determine delimiter
     let delimiter;
     if (detectedDelimiter !== undefined) {
@@ -64,8 +58,19 @@ export function createParseConfig(opts) {
         delimiter = detectedDelimiter;
     }
     else if (delimiterOption === "" && processedInput !== undefined) {
-        // Auto-detect from input (batch mode)
-        delimiter = detectDelimiter(processedInput, quote || '"', delimitersToGuess, comment, shouldSkipEmpty);
+        // Auto-detect from input (batch mode). The same detector a stream uses, fed in one go, so
+        // the two cannot weigh the candidates differently.
+        delimiter = detectDelimiterFor(processedInput, {
+            // "" when quoting is disabled, so detection scores by the grammar the parse will use.
+            quote: quoteEnabled ? quote : "",
+            escape,
+            relaxQuotes,
+            comment,
+            delimitersToGuess,
+            // Only fastMode actually ends records at a configured separator; standard mode always
+            // ends them at CR/LF, so sampling there must not use it.
+            lineEnding: fastMode && linebreakRegex !== DEFAULT_LINEBREAK_REGEX ? linebreak : undefined
+        });
     }
     else if (delimiterOption === "") {
         // Streaming mode with auto-detect - use default, will be updated later
@@ -74,12 +79,6 @@ export function createParseConfig(opts) {
     else {
         delimiter = delimiterOption;
     }
-    // Determine linebreak
-    const linebreak = lineEndingOption || (processedInput !== undefined ? detectLinebreak(processedInput) : "\n");
-    // Pre-compile linebreak regex for fast mode
-    const linebreakRegex = linebreak && linebreak !== "\n" && linebreak !== "\r\n" && linebreak !== "\r"
-        ? linebreak
-        : DEFAULT_LINEBREAK_REGEX;
     const config = {
         delimiter,
         linebreak,

package/dist/esm/modules/csv/parse/delimiter-detector.js

@@ -0,0 +1,276 @@
+/**
+ * Delimiter auto-detection.
+ *
+ * One incremental detector serves both `Csv.parse` and `CsvParserStream`. That is not tidiness:
+ * quote recognition depends on field boundaries, and field boundaries depend on the delimiter
+ * being detected, so a batch parse and a streamed parse of the same bytes can only agree if
+ * they weigh the candidates by identical rules. While these rules lived in two places — a
+ * sampler and a readiness check on the stream — they drifted repeatedly: over what an empty
+ * candidate list means, over whether a comment counts towards the sample, over which record
+ * separator applies, and over how much text is enough.
+ *
+ * The detector keeps *no copy of the input*. Each candidate owns a scanner, and every record
+ * that scanner completes is counted as it arrives. That is what makes the answer independent of
+ * chunking: a candidate is scored on its first `DELIMITER_DETECTION_SAMPLE_RECORDS` complete
+ * records, which is a fact about the bytes rather than about where a chunk boundary fell. It is
+ * also why deciding is O(candidates) rather than a re-walk of everything buffered, and why a
+ * long run of comments cannot grow the detector: those records are consumed like any other.
+ */
+import { createScanner, scanRow } from "./scanner/index.js";
+/** Delimiters weighed when none are given. */
+const AUTO_DETECT_DELIMITERS = [",", ";", "\t", "|"];
+/**
+ * Records each candidate is scored on.
+ *
+ * A stream must hold this many before committing, or its choice — and therefore its rows —
+ * would depend on where the chunk boundaries fell.
+ */
+const SAMPLE_RECORDS = 10;
+/**
+ * Characters of *scorable* records a candidate may be scored on, and the amount of undigested
+ * text after which a candidate is judged unable to complete another record.
+ */
+const SAMPLE_CHARS = 65536;
+/** Fields a candidate must average before it is considered a delimiter at all. */
+const MIN_AVERAGE_FIELDS = 1.99;
+/**
+ * Candidates a detector will weigh.
+ *
+ * An empty list is read as "unset", which is what a caller passing one is asking for. It once
+ * meant "no candidates, fall back to comma" to a batch parse and "not configured, use the
+ * defaults" to a stream, so the same options produced different delimiters.
+ */
+function delimiterCandidates(delimitersToGuess) {
+    return delimitersToGuess && delimitersToGuess.length > 0
+        ? delimitersToGuess
+        : AUTO_DETECT_DELIMITERS;
+}
+/**
+ * Whether a record can contribute to a candidate's score.
+ *
+ * A record that is empty or only whitespace cannot indicate a delimiter, and a comment is not
+ * data. This is deliberately the only copy of the rule: a stream waits for exactly the records
+ * the scoring reads.
+ */
+function isScorableRecord(raw, comment) {
+    if (comment && raw.startsWith(comment)) {
+        return false;
+    }
+    return raw.trim() !== "";
+}
+export function createDelimiterDetector(options) {
+    const quote = options.quote ?? '"';
+    const comment = options.comment;
+    const separator = options.lineEnding;
+    /** Records split by a configured separator rather than by the CSV grammar. */
+    const useSeparator = separator !== undefined && separator !== "";
+    const candidateDelimiters = delimiterCandidates(options.delimitersToGuess);
+    const configFor = (delimiter) => ({
+        delimiter,
+        quote,
+        escape: options.escape ?? quote,
+        quoteEnabled: quote !== "",
+        relaxQuotes: options.relaxQuotes ?? false
+    });
+    let candidates = [];
+    /** Total characters fed, so that undigested text can be measured without keeping it. */
+    let fedChars = 0;
+    /** The record being accumulated on the configured-separator path, which may span chunks. */
+    let pendingRecord = "";
+    let released = false;
+    /** The answer once given, so that a call after `release` cannot report a different one. */
+    let settled;
+    function build() {
+        candidates = candidateDelimiters.map(delimiter => ({
+            scanner: useSeparator ? undefined : createScanner(configFor(delimiter)),
+            config: configFor(delimiter),
+            fieldCounts: [],
+            scoredChars: 0,
+            consumedChars: 0
+        }));
+        fedChars = 0;
+        pendingRecord = "";
+    }
+    build();
+    /** Whether this candidate has all the sample it will be scored on. */
+    const hasFullSample = (candidate) => candidate.fieldCounts.length >= SAMPLE_RECORDS || candidate.scoredChars >= SAMPLE_CHARS;
+    /**
+     * Whether this candidate has stopped being able to complete records.
+     *
+     * Checked only after its scanner has been drained, so undigested text really is text the
+     * candidate cannot turn into a record — a quoted field its grammar never closes. Checking it
+     * before draining made any first chunk of this size look stuck, which decided the delimiter
+     * on however much text happened to arrive first.
+     */
+    const isStuck = (candidate) => fedChars - candidate.consumedChars >= SAMPLE_CHARS;
+    function countRecord(candidate, raw, consumed) {
+        candidate.consumedChars += consumed;
+        if (!isScorableRecord(raw, comment)) {
+            return;
+        }
+        candidate.fieldCounts.push(scanRow(raw, 0, candidate.config, true).fields.length);
+        candidate.scoredChars += raw.length;
+    }
+    function feedSeparatorPath(data) {
+        pendingRecord += data;
+        let at = pendingRecord.indexOf(separator);
+        while (at !== -1) {
+            const raw = pendingRecord.slice(0, at);
+            const consumed = at + separator.length;
+            for (const candidate of candidates) {
+                if (!hasFullSample(candidate)) {
+                    countRecord(candidate, raw, consumed);
+                }
+                else {
+                    candidate.consumedChars += consumed;
+                }
+            }
+            pendingRecord = pendingRecord.slice(consumed);
+            at = pendingRecord.indexOf(separator);
+        }
+    }
+    function feed(data) {
+        if (released || data === "") {
+            return;
+        }
+        fedChars += data.length;
+        if (useSeparator) {
+            feedSeparatorPath(data);
+            return;
+        }
+        for (const candidate of candidates) {
+            const scanner = candidate.scanner;
+            if (!scanner) {
+                continue;
+            }
+            scanner.feed(data);
+            // Drained fully even once the sample is full, so that `consumedChars` keeps pace with the
+            // text and a candidate that is merely finished is never mistaken for one that is stuck.
+            let row = scanner.nextRow();
+            while (row !== null) {
+                const raw = row.raw ?? "";
+                const consumed = raw.length + (row.newline?.length ?? 0);
+                if (hasFullSample(candidate)) {
+                    candidate.consumedChars += consumed;
+                }
+                else {
+                    countRecord(candidate, raw, consumed);
+                }
+                row = scanner.nextRow();
+            }
+        }
+    }
+    /** Take the trailing record, which has no terminator and so is only a record at end of input. */
+    function drainFinalRecords() {
+        if (useSeparator) {
+            if (pendingRecord !== "") {
+                const raw = pendingRecord;
+                for (const candidate of candidates) {
+                    if (!hasFullSample(candidate)) {
+                        countRecord(candidate, raw, raw.length);
+                    }
+                }
+                pendingRecord = "";
+            }
+            return;
+        }
+        for (const candidate of candidates) {
+            let row = candidate.scanner?.flush() ?? null;
+            while (row !== null) {
+                const raw = row.raw ?? "";
+                if (!hasFullSample(candidate)) {
+                    countRecord(candidate, raw, raw.length + (row.newline?.length ?? 0));
+                }
+                row = candidate.scanner?.flush() ?? null;
+            }
+        }
+    }
+    /** Pick the candidate whose field counts are most consistent, then most numerous. */
+    function score() {
+        let best;
+        let bestDelta;
+        let bestAverage;
+        for (let index = 0; index < candidates.length; index++) {
+            const counts = candidates[index].fieldCounts;
+            if (counts.length === 0) {
+                continue;
+            }
+            let delta = 0;
+            let total = 0;
+            let previous;
+            for (const count of counts) {
+                total += count;
+                if (previous !== undefined) {
+                    delta += Math.abs(count - previous);
+                }
+                previous = count;
+            }
+            const average = total / counts.length;
+            if (average <= MIN_AVERAGE_FIELDS) {
+                continue;
+            }
+            if (bestDelta === undefined ||
+                delta < bestDelta ||
+                (delta === bestDelta && (bestAverage === undefined || average > bestAverage))) {
+                bestDelta = delta;
+                bestAverage = average;
+                best = candidateDelimiters[index];
+            }
+        }
+        return best;
+    }
+    /**
+     * Whether waiting could still change the answer.
+     *
+     * Every candidate must have its full sample or have shown it cannot complete another record,
+     * and at least one scorable record must exist — committing on a partial first line is what
+     * once made a stream pick comma for a semicolon-delimited file.
+     */
+    function isReady() {
+        let anyScorable = false;
+        for (const candidate of candidates) {
+            if (!hasFullSample(candidate) && !isStuck(candidate)) {
+                return false;
+            }
+            if (candidate.fieldCounts.length > 0) {
+                anyScorable = true;
+            }
+        }
+        return anyScorable;
+    }
+    return {
+        feed,
+        reset(text) {
+            released = false;
+            build();
+            feed(text);
+        },
+        decide() {
+            if (released || !isReady()) {
+                return undefined;
+            }
+            settled = score();
+            return settled;
+        },
+        decideAtEof() {
+            if (released) {
+                return settled ?? candidateDelimiters[0];
+            }
+            drainFinalRecords();
+            settled = score() ?? candidateDelimiters[0];
+            return settled;
+        },
+        release() {
+            released = true;
+            candidates = [];
+            fedChars = 0;
+            pendingRecord = "";
+        }
+    };
+}
+/** Detect from text already in hand, which is the batch case. */
+export function detectDelimiterFor(input, options) {
+    const detector = createDelimiterDetector(options);
+    detector.feed(input);
+    return detector.decideAtEof();
+}