pivotkit-xlsx 0.0.0-stage → 0.1.0

package/src/reader.js

@@ -0,0 +1,221 @@
+/*
+ * The reader of pivotkit-xlsx (loaded on demand by the plugin in index.js): an Excel workbook (.xlsx)
+ * into a table of pivotkit-core/import.
+ *
+ * 1. Checks of its own before any XML is parsed: the file size (limits.fileBytes); what the file is
+ *    (an .xls, an encrypted workbook, a binary .xlsb or a macro workbook is refused with what to do);
+ *    the ZIP directory: parts (limits.archiveEntries) and unpacked size (limits.unpackedBytes), so a
+ *    ZIP bomb is refused before it is unpacked; no vbaProject.bin; no <!DOCTYPE or <!ENTITY in the
+ *    XML parts it reads.
+ * 2. It unpacks only the parts the chosen sheet needs, each into a buffer of the size the directory
+ *    states, and leaves out the sheet's rows without a value (the used range of formatted empty
+ *    cells, xml.js).
+ * 3. read-excel-file (MIT) parses those parts: shared strings, styles (a date is a number with a date
+ *    format), the values Excel saved (never a formula). It gets them as a ZIP without compression,
+ *    so it unpacks nothing itself and starts no worker: no `blob:` worker, which a strict
+ *    Content-Security-Policy would block.
+ * 4. pivotkit-core's `createTable` finds the header, cleans the values and infers the types, as for
+ *    CSV and JSON.
+ */
+
+import { bytesOf, cleanText, createTable, fileError, fileName, readOptions } from "pivotkit-core/import";
+import { readSheet } from "read-excel-file/universal";
+import { checkXml, createSheetFilter, createXmlCheck } from "./xml.js";
+import { createStoredZip, readDirectory, unpack, unpackStream } from "./zip.js";
+import { sharedParts, worksheets } from "./workbook.js";
+
+const CFB = [0xd0, 0xcf, 0x11, 0xe0, 0xa1, 0xb1, 0x1a, 0xe1];
+const ZIP = [0x50, 0x4b, 0x03, 0x04];
+const startsWith = (bytes, sig) => sig.every((b, i) => bytes[i] === b);
+/** A sheet name in a message: it comes from the file. */
+const shown = (name) => cleanText(String(name)).slice(0, 100);
+/** The most a workbook's list of sheets and its relationships may be; real ones are a few kilobytes. */
+const MAX_WORKBOOK_PART = 4 * 1024 * 1024;
+const ascii = (s) => Array.from(s, (c) => c.charCodeAt(0));
+// a password-protected .xlsx is a compound file holding the encrypted package (UTF-16 stream name)
+const ENCRYPTED_STREAM = ascii("EncryptedPackage").flatMap((c) => [c, 0]);
+
+function containsBytes(bytes, pattern) {
+    const first = pattern[0];
+    for (let i = bytes.indexOf(first); i !== -1 && i <= bytes.length - pattern.length; i = bytes.indexOf(first, i + 1)) {
+        let k = 1;
+        while (k < pattern.length && bytes[i + k] === pattern[k]) k++;
+        if (k === pattern.length) return true;
+    }
+    return false;
+}
+
+/** Refuses what is no .xlsx, with what it is and what to do. */
+function checkKind(bytes, file) {
+    if (/\.xlsm$/i.test(file)) {
+        throw fileError("MACROS", file, "a workbook with macros (.xlsm) is not loaded; save it as an Excel workbook (.xlsx) or as CSV.");
+    }
+    if (startsWith(bytes, CFB)) {
+        if (containsBytes(bytes, ENCRYPTED_STREAM)) {
+            throw fileError("ENCRYPTED", file, "the workbook is protected with a password; save it without one, then load it.");
+        }
+        throw fileError("XLS", file, "this is an Excel 97-2003 workbook (.xls); save it as an Excel workbook (.xlsx) or as CSV, then load it.");
+    }
+    if (!startsWith(bytes, ZIP)) {
+        throw fileError("WRONG_TYPE", file, "this is no Excel workbook (.xlsx); check the file, or load a CSV file with the CSV reader.");
+    }
+}
+
+/**
+ * Reads and checks a workbook's directory and its small parts.
+ * @returns {Promise<{ entries: Map<string, import("./zip.js").ZipEntry>, parts: Map<string, Uint8Array>, sheets: ReturnType<typeof worksheets>, shared: ReturnType<typeof sharedParts> }>}
+ */
+async function open(bytes, file, limits, between) {
+    checkKind(bytes, file);
+    const list = readDirectory(bytes, file, limits);
+    const entries = new Map(list.map((e) => [e.name, e]));
+    for (const e of list) {
+        if (/(^|\/)vbaProject\.bin$/i.test(e.name)) {
+            throw fileError("MACROS", file, "the workbook holds macros (vbaProject.bin); save it as an Excel workbook (.xlsx) without macros, or as CSV.");
+        }
+    }
+    if (!entries.has("xl/workbook.xml")) {
+        if (entries.has("xl/workbook.bin")) {
+            throw fileError("XLSB", file, "this is an Excel binary workbook (.xlsb); save it as an Excel workbook (.xlsx) or as CSV, then load it.");
+        }
+        throw fileError("WRONG_TYPE", file, "this ZIP file is no Excel workbook (it has no xl/workbook.xml).");
+    }
+    /** @type {Map<string, Uint8Array>} */
+    const parts = new Map();
+    const read = async (path, max = Infinity) => {
+        const entry = entries.get(path);
+        if (!entry) return null;
+        if (entry.size > max) {
+            throw fileError("DAMAGED", file, `the part "${path}" is ${entry.size.toLocaleString("en-US")} bytes, far more than a workbook's list of sheets holds; it is refused.`);
+        }
+        const data = await unpack(bytes, entry, file, between);
+        checkXml(data, file, path);
+        parts.set(path, data);
+        return data;
+    };
+    const types = await read("[Content_Types].xml", MAX_WORKBOOK_PART);
+    if (types && /macroEnabled/i.test(new TextDecoder().decode(types))) {
+        throw fileError("MACROS", file, "a workbook with macros (.xlsm) is not loaded; save it as an Excel workbook (.xlsx) or as CSV.");
+    }
+    const decode = (data) => (data ? new TextDecoder().decode(data) : "");
+    const workbook = decode(await read("xl/workbook.xml", MAX_WORKBOOK_PART));
+    const rels = decode(await read("xl/_rels/workbook.xml.rels", MAX_WORKBOOK_PART));
+    const sheets = worksheets(workbook, rels);
+    if (sheets.length === 0) {
+        throw fileError("NO_TABLE", file, "the workbook has no worksheet.");
+    }
+    return { entries, parts, sheets, shared: sharedParts(rels) };
+}
+
+/** The sheet asked for: by name, by index (0-based), else the first visible one. */
+function pickSheet(sheets, wanted, file) {
+    if (typeof wanted === "string") {
+        const s = sheets.find((x) => x.name === wanted);
+        if (!s) throw fileError("NO_SHEET", file, `the workbook has no sheet "${shown(wanted)}".`, { sheet: wanted });
+        return s;
+    }
+    if (typeof wanted === "number") {
+        const s = sheets[wanted];
+        if (!s) throw fileError("NO_SHEET", file, `the workbook has no sheet ${wanted + 1}.`, { sheet: wanted });
+        return s;
+    }
+    return sheets.find((s) => s.visible) ?? sheets[0];
+}
+
+/**
+ * The worksheets of a workbook: name, index (0-based) and whether it is visible.
+ * @param {Blob | ArrayBuffer | Uint8Array} file
+ * @param {import("pivotkit-core/import").ReadOptions} [options]
+ * @returns {Promise<import("pivotkit-core/import").SheetInfo[]>}
+ */
+export async function sheets(file, options) {
+    const o = readOptions(options);
+    const name = fileName(file, o);
+    const bytes = await bytesOf(file, o.limits, name);
+    const { sheets: list } = await open(bytes, name, o.limits, () => o.signal?.throwIfAborted());
+    return list.map(({ name: sheet, index, visible }) => ({ name: sheet, index, visible }));
+}
+
+/**
+ * Reads one sheet of a workbook into a table: `options.sheet` (a name, or an index from 0), else the
+ * first visible one.
+ * @param {Blob | ArrayBuffer | Uint8Array} file
+ * @param {import("pivotkit-core/import").ReadOptions} [options]
+ * @returns {Promise<import("pivotkit-core/import").ImportTable>}
+ */
+export async function read(file, options) {
+    const o = readOptions(options);
+    const name = fileName(file, o);
+    const signal = o.signal;
+    signal?.throwIfAborted();
+    const bytes = await bytesOf(file, o.limits, name);
+    o.onProgress?.({ phase: "read", done: bytes.length, total: bytes.length });
+    const between = () => signal?.throwIfAborted();
+    const { entries, parts, sheets: list, shared } = await open(bytes, name, o.limits, between);
+    const sheet = pickSheet(list, o.sheet, name);
+
+    for (const path of [shared.sharedStrings, shared.styles]) {
+        const entry = entries.get(path);
+        if (entry && !parts.has(path)) {
+            const data = await unpack(bytes, entry, name, between);
+            checkXml(data, name, path);
+            parts.set(path, data);
+        }
+    }
+    const entry = entries.get(sheet.path);
+    if (!entry) throw fileError("DAMAGED", name, `the part of sheet "${shown(sheet.name)}" is missing; open the workbook in Excel and save it again.`);
+    // read-excel-file reads the parts from a ZIP: one without compression, of only these parts, with
+    // the sheet's rows without a value left out while it streams in
+    // sized for the whole sheet: the buffer never grows (no copy); what the filter leaves out is never
+    // written, and transfer() below gives the unused end back
+    let room = entry.size + 22;
+    for (const [path, data] of parts) room += data.length + 2 * (76 + path.length);
+    const zip = createStoredZip(room + 2 * (76 + sheet.path.length));
+    for (const [path, data] of parts) zip.add(path, data);
+    parts.clear();
+    const sheetPart = zip.begin(sheet.path);
+    // a title block above the header may hold a few rows more than the table
+    const filter = createSheetFilter(sheetPart, { file: name, maxRow: o.limits.rows + 1_000, maxColumn: o.limits.columns, maxCells: o.limits.importCells + o.limits.columns * 1_000 });
+    const check = createXmlCheck(name, sheet.path);
+    let unpacked = 0;
+    await unpackStream(bytes, entry, name, (chunk) => {
+        check(chunk);
+        filter.push(chunk);
+        unpacked += chunk.length;
+    }, () => {
+        signal?.throwIfAborted();
+        o.onProgress?.({ phase: "unpack", done: unpacked, total: entry.size });
+    });
+    const trimmed = filter.end();
+    sheetPart.end();
+    let stored = zip.finish();
+    signal?.throwIfAborted();
+    o.onProgress?.({ phase: "parse", done: 0, total: trimmed.lastValueRow });
+    /** @type {unknown[][]} */
+    let rows;
+    try {
+        // an ArrayBuffer of the ZIP's length: transfer() shrinks the buffer, where it can, without a copy
+        const whole = /** @type {ArrayBuffer & { transfer?: (length: number) => ArrayBuffer }} */ (stored.buffer);
+        const buffer = whole.byteLength === stored.length ? whole : typeof whole.transfer === "function" ? whole.transfer(stored.length) : stored.slice().buffer;
+        stored = null;
+        rows = await readSheet(buffer, sheet.name);
+    } catch (error) {
+        throw fileError("DAMAGED", name, `sheet "${shown(sheet.name)}" cannot be read (${String(/** @type {Error} */ (error)?.message ?? error).slice(0, 200)}); open the workbook in Excel and save it again.`);
+    }
+    signal?.throwIfAborted();
+    o.onProgress?.({ phase: "parse", done: trimmed.lastValueRow, total: trimmed.lastValueRow });
+
+    const table = createTable({ file: name, limits: o.limits, locale: o.locale, hints: { decimal: ".", serialDates: true } });
+    table.note("SHEET", { sheet: sheet.name, count: list.length, visible: list.filter((s) => s.visible).length });
+    if (trimmed.lastRow > trimmed.lastValueRow && trimmed.lastRow - trimmed.lastValueRow >= 100) {
+        table.note("USED_RANGE", { usedRow: trimmed.lastRow, lastRow: trimmed.lastValueRow });
+    }
+    for (let r = 0; r < rows.length; r++) {
+        table.row(rows[r]);
+        rows[r] = null;
+    }
+    // read-excel-file reads a cell with an error (#N/A, #DIV/0!) as empty; the filter counted them
+    if (trimmed.errors > 0) table.note("ERROR_CELLS", { count: trimmed.errors });
+    signal?.throwIfAborted();
+    return table.finish(o.types);
+}

package/src/workbook.js

@@ -0,0 +1,79 @@
+/*
+ * The sheets of a workbook (xl/workbook.xml) and the parts they are in (xl/_rels/workbook.xml.rels):
+ * names, order, hidden or not, and the path of each worksheet. Both parts are small and plain; their
+ * elements are read with patterns over the text after the XML check (xml.js). Not part of the public
+ * API.
+ */
+
+const ENTITIES = { amp: "&", lt: "<", gt: ">", quot: '"', apos: "'" };
+
+/** XML text with its five named entities and character references decoded. */
+export function decodeXml(text) {
+    return text.replace(/&(?:#x([0-9a-f]{1,6})|#(\d{1,7})|(amp|lt|gt|quot|apos));/gi, (whole, hex, dec, name) => {
+        if (name) return ENTITIES[name.toLowerCase()] ?? whole;
+        const code = hex ? parseInt(hex, 16) : Number(dec);
+        return code > 0 && code <= 0x10ffff ? String.fromCodePoint(code) : "";
+    });
+}
+
+/** The attributes of one start tag's text (`name="..."`, prefixes dropped: `r:id` is `id`). */
+function attributes(tag) {
+    /** @type {Map<string, string>} */
+    const out = new Map();
+    for (const m of tag.matchAll(/(?:[\w.-]+:)?([\w.-]+)\s*=\s*("([^"]*)"|'([^']*)')/g)) {
+        if (!out.has(m[1])) out.set(m[1], decodeXml(m[3] ?? m[4] ?? ""));
+    }
+    return out;
+}
+
+/** The start tags of elements named `local` (any namespace prefix). */
+function tags(xml, local) {
+    // [^<>]: a tag never holds "<", so each attempt ends at the next one: linear, also for "<sheet" repeated without ">"
+    return [...xml.matchAll(new RegExp(`<(?:[\\w.-]+:)?${local}\\b([^<>]*)>`, "g"))].map((m) => attributes(m[1]));
+}
+
+/** "worksheets/sheet1.xml" relative to xl/ (or "/xl/..." absolute) -> "xl/worksheets/sheet1.xml" */
+export function partPath(target) {
+    const parts = (target.startsWith("/") ? target.slice(1) : `xl/${target}`).split("/");
+    const out = [];
+    for (const p of parts) {
+        if (p === "..") out.pop();
+        else if (p !== "." && p !== "") out.push(p);
+    }
+    return out.join("/");
+}
+
+/**
+ * The worksheets of a workbook in their order (chart sheets and dialog sheets are not tables).
+ * @param {string} workbookXml
+ * @param {string} relsXml
+ * @returns {Array<{ name: string, index: number, visible: boolean, path: string }>}
+ */
+export function worksheets(workbookXml, relsXml) {
+    const targets = new Map();
+    for (const rel of tags(relsXml, "Relationship")) {
+        const type = rel.get("Type") ?? "";
+        if (/\/worksheet$/.test(type) && rel.has("Id") && rel.has("Target") && rel.get("TargetMode") !== "External") {
+            targets.set(rel.get("Id"), partPath(rel.get("Target")));
+        }
+    }
+    const out = [];
+    for (const sheet of tags(workbookXml, "sheet")) {
+        const path = targets.get(sheet.get("id") ?? "");
+        if (path === undefined) continue;
+        const state = sheet.get("state");
+        out.push({ name: sheet.get("name") ?? "", index: out.length, visible: state !== "hidden" && state !== "veryHidden", path });
+    }
+    return out;
+}
+
+/** The paths of the shared strings and the styles, from the workbook's relationships. */
+export function sharedParts(relsXml) {
+    const out = { sharedStrings: "xl/sharedStrings.xml", styles: "xl/styles.xml" };
+    for (const rel of tags(relsXml, "Relationship")) {
+        const type = rel.get("Type") ?? "";
+        if (/\/sharedStrings$/.test(type) && rel.has("Target")) out.sharedStrings = partPath(rel.get("Target"));
+        if (/\/styles$/.test(type) && rel.has("Target")) out.styles = partPath(rel.get("Target"));
+    }
+    return out;
+}

package/src/xml.js

@@ -0,0 +1,278 @@
+/*
+ * Checks and trims of the XML parts of a workbook, on their bytes, before read-excel-file sees them:
+ *
+ * - `checkXml`: no document type declaration and no entity declaration (`<!DOCTYPE`, `<!ENTITY`).
+ *   An .xlsx never needs either; refusing them rules out entity expansion and external entities
+ *   whatever the XML parser does with them.
+ * - `createSheetFilter`: the rows of a sheet that hold no value are left out. Excel's used range often
+ *   reaches far below the data (formatted empty cells to row 900,000); those rows would otherwise be
+ *   unpacked into memory, parsed and turned into empty rows. A row is kept when it has a cell with
+ *   content (`</c>`: a value, an inline string or a formula); a row of empty cells (`<c r="A9" s="1"/>`)
+ *   or a self-closing `<row/>` goes. Rows are numbered by their cells' `r` attributes, so leaving rows
+ *   out moves no value.
+ *
+ * Not part of the public API.
+ */
+
+import { fileError, limitError } from "pivotkit-core/import";
+
+const ascii = (s) => Uint8Array.from(s, (c) => c.charCodeAt(0));
+const LT = 0x3c;
+const BANG = 0x21;
+const DOCTYPE = ascii("DOCTYPE");
+const ENTITY = ascii("ENTITY");
+const SHEET_DATA = ascii("<sheetData");
+const SHEET_DATA_END = ascii("</sheetData>");
+const ROW = ascii("<row");
+const ROW_END = ascii("</row>");
+const CELL_END = ascii("</c>");
+const ERROR_TYPE = ascii(' t="e"');
+
+/** Index of `pattern` in `buf` from `from`, or -1. */
+export function indexOf(buf, pattern, from = 0, to = buf.length) {
+    const first = pattern[0];
+    const last = to - pattern.length;
+    for (let i = buf.indexOf(first, from); i !== -1 && i <= last; i = buf.indexOf(first, i + 1)) {
+        let k = 1;
+        while (k < pattern.length && buf[i + k] === pattern[k]) k++;
+        if (k === pattern.length) return i;
+    }
+    return -1;
+}
+
+/** Whether `buf` at `i` holds `word`, letters compared without case. */
+function wordAt(buf, i, word) {
+    for (let k = 0; k < word.length; k++) {
+        if ((buf[i + k] | 0x20) !== (word[k] | 0x20)) return false;
+    }
+    return true;
+}
+
+/**
+ * A check of an XML part's bytes, fed piece by piece: throws at a `<!DOCTYPE` or `<!ENTITY`.
+ * @param {string} file
+ * @param {string} part
+ */
+export function createXmlCheck(file, part) {
+    let tail = new Uint8Array(0);
+    let first = true;
+    return (chunk) => {
+        // the check reads ASCII bytes: an XML part in UTF-16 or UTF-32 (a byte order mark, zero bytes)
+        // could hide a declaration from it, and Excel writes UTF-8
+        if ((first && chunk.length >= 2 && ((chunk[0] === 0xfe && chunk[1] === 0xff) || (chunk[0] === 0xff && chunk[1] === 0xfe))) || chunk.indexOf(0) !== -1) {
+            throw fileError("XML_DECLARATION", file, `the part "${part}" is not UTF-8 XML, which a workbook always is; it is refused.`, { part });
+        }
+        first = false;
+        const buf = tail.length ? concat(tail, chunk) : chunk;
+        // "!" is rare in a workbook's XML (comments, CDATA, text); "<" is in every tag
+        for (let i = buf.indexOf(BANG, 1); i !== -1; i = buf.indexOf(BANG, i + 1)) {
+            if (buf[i - 1] === LT && (wordAt(buf, i + 1, DOCTYPE) || wordAt(buf, i + 1, ENTITY))) {
+                throw fileError("XML_DECLARATION", file, `the part "${part}" declares a document type or entities, which a workbook never needs; it is refused.`, { part });
+            }
+        }
+        tail = buf.slice(Math.max(0, buf.length - 9));
+    };
+}
+
+/** Checks a whole XML part. */
+export function checkXml(bytes, file, part) {
+    createXmlCheck(file, part)(bytes);
+}
+
+function concat(a, b) {
+    const out = new Uint8Array(a.length + b.length);
+    out.set(a);
+    out.set(b, a.length);
+    return out;
+}
+
+/** The row number of a `<row ...>` tag (its `r` attribute), or 0. */
+function rowNumber(buf, from, to) {
+    for (let i = from; i < to - 3; i++) {
+        // ' r="'
+        if ((buf[i] === 0x20 || buf[i] === 0x09 || buf[i] === 0x0a || buf[i] === 0x0d) && buf[i + 1] === 0x72 && buf[i + 2] === 0x3d && buf[i + 3] === 0x22) {
+            let n = 0;
+            for (let k = i + 4; k < to && buf[k] >= 0x30 && buf[k] <= 0x39; k++) n = n * 10 + (buf[k] - 0x30);
+            return n;
+        }
+    }
+    return 0;
+}
+
+/** The largest row (or start of a sheet before its <sheetData>) the filter holds while it waits for its end. */
+const MAX_PENDING = 64 * 1024 * 1024;
+const CELL = ascii("<c ");
+
+/** The highest column (1 for A) and row of the cells' `r` attributes in buf[from, to). */
+function cellExtent(buf, from, to) {
+    let column = 0;
+    let row = 0;
+    for (let i = indexOf(buf, CELL, from, to); i !== -1; i = indexOf(buf, CELL, i + 3, to)) {
+        const gt = buf.indexOf(0x3e, i);
+        const stop = gt === -1 || gt > to ? to : gt;
+        for (let k = i + 2; k < stop - 3; k++) {
+            if ((buf[k] === 0x20 || buf[k] === 0x09) && buf[k + 1] === 0x72 && buf[k + 2] === 0x3d && buf[k + 3] === 0x22) {
+                let c = 0;
+                let q = k + 4;
+                for (; q < stop && ((buf[q] | 0x20) >= 0x61 && (buf[q] | 0x20) <= 0x7a) && c <= 1e7; q++) c = c * 26 + ((buf[q] | 0x20) - 0x60);
+                let r = 0;
+                for (; q < stop && buf[q] >= 0x30 && buf[q] <= 0x39 && r <= 1e12; q++) r = r * 10 + (buf[q] - 0x30);
+                column = Math.max(column, c);
+                row = Math.max(row, r);
+                break;
+            }
+        }
+    }
+    return { column, row };
+}
+
+/**
+ * Streams a sheet's XML and leaves out its rows without a value. Feed pieces with `push`; the XML
+ * kept goes to `out.write`; `end()` gives the row numbers seen.
+ *
+ * It also checks where the values are against the limits, before read-excel-file sees them: the
+ * parser makes a dense array of the sheet's extent (every row up to the last row with a value, each
+ * as wide as the widest), so a value in row 1,000,000 or column XFD costs that much memory however
+ * small the file is. A value beyond `maxRow` or `maxColumn`, or an extent of more than `maxCells`,
+ * stops the read with LIMIT_EXCEEDED.
+ * @param {{ write: (bytes: Uint8Array, from?: number, to?: number) => void }} out
+ * @param {{ file?: string, maxRow?: number, maxColumn?: number, maxCells?: number }} [limits]
+ */
+export function createSheetFilter(out, limits = {}) {
+    const file = limits.file ?? "file";
+    let widest = 0;
+    let state = 0; // 0 before <sheetData>, 1 inside, 2 after
+    let pending = new Uint8Array(0);
+    let lastValueRow = 0;
+    let lastRow = 0;
+    let dropped = 0;
+    let errors = 0;
+
+    const run = (final) => {
+        const buf = pending;
+        let i = 0;
+        while (i < buf.length) {
+            if (state === 0) {
+                const at = indexOf(buf, SHEET_DATA, i);
+                if (at === -1) {
+                    const keep = final ? buf.length : Math.max(i, buf.length - SHEET_DATA.length);
+                    out.write(buf, i, keep);
+                    i = keep;
+                    break;
+                }
+                const close = buf.indexOf(0x3e, at);
+                if (close === -1) {
+                    out.write(buf, i, at);
+                    i = at;
+                    break;
+                }
+                out.write(buf, i, close + 1);
+                i = close + 1;
+                state = buf[close - 1] === 0x2f ? 2 : 1; // <sheetData/>
+                continue;
+            }
+            if (state === 2) {
+                out.write(buf, i, buf.length);
+                i = buf.length;
+                break;
+            }
+            // inside <sheetData>: whole rows at a time
+            const lt = buf.indexOf(LT, i);
+            if (lt === -1) {
+                i = buf.length; // whitespace between rows
+                break;
+            }
+            if (indexOf(buf, SHEET_DATA_END, lt, lt + SHEET_DATA_END.length) === lt) {
+                state = 2;
+                i = lt;
+                continue;
+            }
+            if (indexOf(buf, ROW, lt, lt + ROW.length) !== lt) {
+                // anything else in sheetData (a comment, say) is kept as it is
+                const gt = buf.indexOf(0x3e, lt);
+                if (gt === -1) {
+                    i = lt;
+                    break;
+                }
+                out.write(buf, lt, gt + 1);
+                i = gt + 1;
+                continue;
+            }
+            const tagEnd = buf.indexOf(0x3e, lt);
+            if (tagEnd === -1) {
+                i = lt;
+                break;
+            }
+            const number = rowNumber(buf, lt, tagEnd);
+            if (buf[tagEnd - 1] === 0x2f) {
+                // <row .../>: no cells
+                lastRow = Math.max(lastRow, number);
+                dropped++;
+                i = tagEnd + 1;
+                continue;
+            }
+            const end = indexOf(buf, ROW_END, tagEnd);
+            if (end === -1) {
+                i = lt;
+                break;
+            }
+            const stop = end + ROW_END.length;
+            lastRow = Math.max(lastRow, number);
+            if (indexOf(buf, CELL_END, tagEnd, end) !== -1) {
+                const extent = cellExtent(buf, tagEnd, end);
+                const at = Math.max(number, extent.row);
+                widest = Math.max(widest, extent.column);
+                if (limits.maxRow !== undefined && at > limits.maxRow) throw limitError("rows", at, limits.maxRow, file, "rows");
+                if (limits.maxColumn !== undefined && widest > limits.maxColumn) throw limitError("columns", widest, limits.maxColumn, file, "columns");
+                if (limits.maxCells !== undefined && at * widest > limits.maxCells) throw limitError("importCells", at * widest, limits.maxCells, file, "values (rows x columns)");
+                out.write(buf, lt, stop);
+                lastValueRow = Math.max(lastValueRow, at);
+                for (let e = indexOf(buf, ERROR_TYPE, tagEnd, end); e !== -1; e = indexOf(buf, ERROR_TYPE, e + 1, end)) errors++;
+            } else {
+                dropped++;
+            }
+            i = stop;
+        }
+        pending = i < buf.length ? buf.slice(i) : new Uint8Array(0);
+        if (pending.length > MAX_PENDING) {
+            throw fileError("DAMAGED", file, "a row of the sheet is larger than 64 MiB, or the sheet's XML is broken; the workbook is refused.");
+        }
+    };
+
+    // pieces wait until they double what is pending, so a long row is scanned a few times, not once per piece
+    let waiting = [];
+    let size = 0;
+    let need = 0;
+    const gather = () => {
+        if (waiting.length === 1) return waiting[0];
+        const all = new Uint8Array(size);
+        let at = 0;
+        for (const w of waiting) {
+            all.set(w, at);
+            at += w.length;
+        }
+        return all;
+    };
+
+    return {
+        /** @param {Uint8Array} chunk */
+        push(chunk) {
+            waiting.push(chunk);
+            size += chunk.length;
+            if (size < need) return;
+            pending = gather();
+            run(false);
+            waiting = pending.length ? [pending] : [];
+            size = pending.length;
+            need = pending.length * 2;
+        },
+        /** @returns {{ lastRow: number, lastValueRow: number, dropped: number, errors: number }} */
+        end() {
+            pending = size ? gather() : new Uint8Array(0);
+            waiting = [];
+            run(true);
+            if (pending.length) out.write(pending);
+            return { lastRow, lastValueRow, dropped, errors };
+        }
+    };
+}