From a37a0423a12267589ad400fab14aeaad0200b28c Mon Sep 17 00:00:00 2001
From: baseballyama <xydybaseball@gmail.com>
Date: Sun, 11 Oct 2026 15:43:17 +0900
Subject: [PATCH 1/2] perf(streaming): speed up iterRows on wide sheets of
 styled empty cells (#302)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A sheet whose rows carry hundreds of `<c r="X1" s="n"/>` cells is nearly
all SAX events and almost no values, so the per-event cost of the row
walk dominated: each event was allocated as an object with Clark-notation
names and attributes and handed through an async generator step. The
walk now registers its handlers on saxes directly and only crosses an
async boundary once per 64K feed, which brings it under loadWorkbook's
time for the same bytes instead of 1.5–3x over it.

The saxes driver moves to an internal module so no public declaration
imports saxes' types, which do not type-check under skipLibCheck: false.

coordinateToTuple also reads the plain "AB12" shape off char codes ahead
of the regex, which both readers call once per cell.

Closes #302

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0142ArZjzXh8UP4dVS623qG3
---
 .changeset/fast-styled-empty-cells.md   |   5 +
 src/streaming/read-only.ts              | 233 +++++++++++++-----------
 src/utils/coordinate.ts                 |  19 ++
 src/xml/iterparse.ts                    | 191 +------------------
 src/xml/sax-feed.ts                     | 187 +++++++++++++++++++
 tests/perf/iter-rows-throughput.test.ts |  96 ++++++++++
 6 files changed, 444 insertions(+), 287 deletions(-)
 create mode 100644 .changeset/fast-styled-empty-cells.md
 create mode 100644 src/xml/sax-feed.ts
 create mode 100644 tests/perf/iter-rows-throughput.test.ts

diff --git a/.changeset/fast-styled-empty-cells.md b/.changeset/fast-styled-empty-cells.md
new file mode 100644
index 00000000..bc8f8471
--- /dev/null
+++ b/.changeset/fast-styled-empty-cells.md
@@ -0,0 +1,5 @@
+---
+'@office-kit/xlsx': patch
+---
+
+perf: `loadWorkbookStream`'s `iterRows` / `iterValues` no longer slow down on wide sheets full of styled empty cells (`<c r="X1" s="n"/>`), the shape many business exports have. The row walk now drives the XML parser directly instead of handing each SAX event through an async iterator, which makes it several times faster on such sheets; cell references are also parsed without a regex, which speeds up `loadWorkbook` too (#302)
diff --git a/src/streaming/read-only.ts b/src/streaming/read-only.ts
index 611a81c9..4a9b3d89 100644
--- a/src/streaming/read-only.ts
+++ b/src/streaming/read-only.ts
@@ -3,7 +3,7 @@
 // `loadWorkbookStream` opens the zip + parses workbook.xml / sharedStrings.xml
 // / styles.xml metadata up front (small even on million-row archives), then
 // exposes a lazy `openWorksheet(name)` that SAX-iterates the sheet body via
-// `iterParse`. The iterator streams rows without materialising the full sheet
+// `feedSax`. The iterator streams rows without materialising the full sheet
 // in memory.
 
 import { normalizeStrictArchive } from '../io/strict.js';
@@ -14,7 +14,7 @@ import {
   type SharedStringEntry,
   type SharedStringsTable,
 } from '../workbook/shared-strings.js';
-import { ARC_CONTENT_TYPES, ARC_ROOT_RELS, localNameOf } from '../xml/namespaces.js';
+import { ARC_CONTENT_TYPES, ARC_ROOT_RELS, qname } from '../xml/namespaces.js';
 import { findById, findByType, makeRelationships, relsFromBytes } from '../packaging/relationships.js';
 import { manifestFromBytes } from '../packaging/manifest.js';
 import { parseCellNumber } from '../utils/cell-number.js';
@@ -35,7 +35,9 @@ import { parseCellDate } from '../utils/cell-date.js';
 import { parseCellErrorCode } from '../utils/cell-error.js';
 import { unknownCellType } from '../utils/cell-text.js';
 import { parseXsdBoolean } from '../utils/xsd-boolean.js';
-import { iterParse, type SaxEvent, type SaxInput } from '../xml/iterparse.js';
+import { SaxesParser } from 'saxes';
+import type { SaxInput } from '../xml/iterparse.js';
+import { buildAttrsClark, feedSax } from '../xml/sax-feed.js';
 import { el, type XmlNode } from '../xml/tree.js';
 import { resolveRelTarget } from '../packaging/part-name.js';
 import { parseXml } from '../xml/parser.js';
@@ -182,7 +184,6 @@ async function* iterSheetRows(
   const minCol = opts.minCol ?? 1;
   const maxCol = opts.maxCol ?? Number.POSITIVE_INFINITY;
 
-  let inSheetData = false;
   // -1: outside a <row>. 0: inside one that carried no `@r`, whose number the
   // first located cell settles. `nextRow` is the high-water mark a row with
   // neither an `@r` nor a located cell falls back to.
@@ -223,112 +224,126 @@ async function* iterSheetRows(
   const isStack: XmlNode[] = [];
 
   let checkedRoot = false;
-  for await (const ev of iterParse(sheetInput)) {
-    const e = ev as SaxEvent;
-    if (e.kind === 'start') {
-      if (!checkedRoot) {
-        assertNotStrictRoot(e.name);
-        checkedRoot = true;
-      }
-      // Inside `<is>`, every descendant belongs to the subtree, so this runs
-      // ahead of the local-name switch rather than through it.
-      if (isStack.length > 0) {
-        const child = el(e.name, { ...e.attrs });
-        isStack[isStack.length - 1]?.children.push(child);
-        isStack.push(child);
-        continue;
-      }
-      const local = localNameOf(e.name);
-      if (!inSheetData) {
-        if (local === 'sheetData') inSheetData = true;
-        continue;
-      }
-      if (local === 'is' && cellOpen) {
-        isNode = el(e.name);
-        isStack.push(isNode);
-        continue;
+  let inSheetData = false;
+  // Set once `</sheetData>` closes or the band is passed. The rest of the
+  // current feed still runs through saxes, but contributes nothing.
+  let finished = false;
+  // Rows completed by the current feed. The handlers below run synchronously
+  // inside saxes, one feed at a time, so a whole-sheet pass costs one async
+  // step per feed rather than one per SAX event. On a wide sheet of styled
+  // empty cells the per-event path is what dominated (#302).
+  const ready: ReadOnlyCell[][] = [];
+
+  const parser = new SaxesParser({ xmlns: true });
+  parser.on('opentag', (node) => {
+    if (finished) return;
+    if (!checkedRoot) {
+      assertNotStrictRoot(qname(node.uri, node.local));
+      checkedRoot = true;
+    }
+    // Inside `<is>`, every descendant belongs to the subtree, so this runs
+    // ahead of the local-name switch rather than through it.
+    if (isStack.length > 0) {
+      const child = el(qname(node.uri, node.local), buildAttrsClark(node.attributes));
+      isStack[isStack.length - 1]?.children.push(child);
+      isStack.push(child);
+      return;
+    }
+    const local = node.local;
+    if (!inSheetData) {
+      if (local === 'sheetData') inSheetData = true;
+      return;
+    }
+    if (local === 'is' && cellOpen) {
+      isNode = el(qname(node.uri, node.local));
+      isStack.push(isNode);
+      return;
+    }
+    switch (local) {
+      case 'row': {
+        // `@r` is optional on CT_Row (ECMA-376 §18.3.1.73); such a row waits
+        // for its first cell to name it.
+        const rRaw = node.attributes['r']?.value;
+        if (rRaw === undefined) {
+          chargeRow(budget, title, undefined);
+          currentRow = 0;
+        } else {
+          currentRow = rowNumberFromAttr(rRaw, 'loadWorkbookStream');
+          nextRow = Math.max(nextRow, currentRow + 1);
+          // Charged here rather than at `</row>` so a row past the cap is
+          // refused before its cells are decoded. Unnumbered rows are
+          // charged at their opening tag too, before buffering any cells.
+          chargeRow(budget, title, currentRow);
+        }
+        currentCells = [];
+        pendingCells = [];
+        nextCol = 1;
+        break;
       }
-      switch (local) {
-        case 'row': {
-          // `@r` is optional on CT_Row (ECMA-376 §18.3.1.73); such a row waits
-          // for its first cell to name it.
-          const rRaw = e.attrs['r'];
-          if (rRaw === undefined) {
-            chargeRow(budget, title, undefined);
-            currentRow = 0;
-          } else {
-            currentRow = rowNumberFromAttr(rRaw, 'loadWorkbookStream');
-            nextRow = Math.max(nextRow, currentRow + 1);
-            // Charged here rather than at `</row>` so a row past the cap is
-            // refused before its cells are decoded. Unnumbered rows are
-            // charged at their opening tag too, before buffering any cells.
-            chargeRow(budget, title, currentRow);
-          }
-          currentCells = [];
-          pendingCells = [];
-          nextCol = 1;
-          break;
+      case 'c': {
+        if (currentRow < 0) break;
+        const ref = node.attributes['r']?.value;
+        if (currentRow === 0 && ref) settleRow(coordinateToTuple(ref).row);
+        // Skip cell-attr parsing entirely when the row is outside the
+        // requested band — saves the parseInt + coordinateToTuple hit on
+        // every cell of every excluded row.
+        if (currentRow !== 0 && (currentRow < minRow || currentRow > maxRow)) break;
+        cellType = node.attributes['t']?.value ?? 'n';
+        const sRaw = node.attributes['s']?.value;
+        cellStyleId = sRaw ? Number.parseInt(sRaw, 10) || 0 : 0;
+        if (ref) {
+          const tup = coordinateToTuple(ref);
+          cellRow = tup.row;
+          cellCol = tup.col;
+        } else {
+          cellRow = currentRow;
+          cellCol = nextCol;
         }
-        case 'c': {
-          if (currentRow < 0) break;
-          const ref = e.attrs['r'];
-          if (currentRow === 0 && ref) settleRow(coordinateToTuple(ref).row);
-          // Skip cell-attr parsing entirely when the row is outside the
-          // requested band — saves the parseInt + coordinateToTuple hit on
-          // every cell of every excluded row.
-          if (currentRow !== 0 && (currentRow < minRow || currentRow > maxRow)) break;
-          cellType = e.attrs['t'] ?? 'n';
-          const sRaw = e.attrs['s'];
-          cellStyleId = sRaw ? Number.parseInt(sRaw, 10) || 0 : 0;
-          if (ref) {
-            const tup = coordinateToTuple(ref);
-            cellRow = tup.row;
-            cellCol = tup.col;
-          } else {
-            cellRow = currentRow;
-            cellCol = nextCol;
-          }
-          nextCol = cellCol + 1;
-          cellOpen = cellCol >= minCol && cellCol <= maxCol;
-          if (cellOpen) {
-            // An unresolved row might be selected later, so its buffered cells
-            // consume budget even if its eventual number is outside the band.
-            chargeCell(budget, title, cellCol, cellRow === 0 ? undefined : cellRow);
-          }
-          vText = '';
-          isNode = undefined;
-          isStack.length = 0;
-          break;
+        nextCol = cellCol + 1;
+        cellOpen = cellCol >= minCol && cellCol <= maxCol;
+        if (cellOpen) {
+          // An unresolved row might be selected later, so its buffered cells
+          // consume budget even if its eventual number is outside the band.
+          chargeCell(budget, title, cellCol, cellRow === 0 ? undefined : cellRow);
         }
-        case 'v':
-          if (cellOpen) inV = true;
-          break;
-        default:
-          break;
+        vText = '';
+        isNode = undefined;
+        isStack.length = 0;
+        break;
       }
-      continue;
+      case 'v':
+        if (cellOpen) inV = true;
+        break;
+      default:
+        break;
     }
-    if (e.kind === 'text') {
-      if (inV) vText += e.text;
-      else if (isStack.length > 0) {
-        // Text events for one element accumulate before `parseRichString` sees
-        // them, so a chunk boundary inside a `<t>` cannot split an escape
-        // sequence, and adjacent runs cannot join into one.
-        const top = isStack[isStack.length - 1];
-        if (top !== undefined) top.text = (top.text ?? '') + e.text;
-      }
-      continue;
+  });
+
+  const onText = (text: string): void => {
+    if (finished) return;
+    if (inV) vText += text;
+    else if (isStack.length > 0) {
+      // Text events for one element accumulate before `parseRichString` sees
+      // them, so a chunk boundary inside a `<t>` cannot split an escape
+      // sequence, and adjacent runs cannot join into one.
+      const top = isStack[isStack.length - 1];
+      if (top !== undefined) top.text = (top.text ?? '') + text;
     }
-    // end
+  };
+  parser.on('text', onText);
+  // A CDATA section is character data like any other.
+  parser.on('cdata', onText);
+
+  parser.on('closetag', (node) => {
+    if (finished) return;
     if (isStack.length > 0) {
       isStack.pop();
-      continue;
+      return;
     }
-    const local = localNameOf(e.name);
-    if (!inSheetData) continue;
-    switch (local) {
+    if (!inSheetData) return;
+    switch (node.local) {
       case 'sheetData':
-        inSheetData = false;
+        finished = true;
         return;
       case 'row': {
         // A row that held no located cell still consumes a slot, so settle it
@@ -337,13 +352,13 @@ async function* iterSheetRows(
           settleRow(derivedRowNumber(nextRow, 'loadWorkbookStream'));
         }
         if (currentRow >= minRow && currentRow <= maxRow && currentCells.length > 0) {
-          yield currentCells;
+          ready.push(currentCells);
         }
         // Once we've crossed maxRow there are no more rows to yield — every
         // subsequent <row> would just be parsed and dropped. Stop iterating
         // early. ECMA-376 emits rows in ascending order.
         if (currentRow > maxRow) {
-          inSheetData = false;
+          finished = true;
           return;
         }
         currentRow = -1;
@@ -367,6 +382,20 @@ async function* iterSheetRows(
       default:
         break;
     }
+  });
+
+  try {
+    for await (const _ of feedSax(sheetInput, parser)) {
+      yield* ready;
+      ready.length = 0;
+      if (finished) return;
+    }
+  } catch (err) {
+    // A feed that failed part-way still completed the rows ahead of the
+    // failure; a caller reading up to a content limit or a corrupt cell gets
+    // them before the error, as it would from a walk one event at a time.
+    yield* ready;
+    throw err;
   }
 }
 
diff --git a/src/utils/coordinate.ts b/src/utils/coordinate.ts
index 240da5d9..25a72329 100644
--- a/src/utils/coordinate.ts
+++ b/src/utils/coordinate.ts
@@ -131,6 +131,25 @@ export function coordinateFromString(coord: string): CellCoordinate {
  * numeric index. Thin convenience for the worksheet read path.
  */
 export function coordinateToTuple(coord: string): CellCoordinateNumeric {
+  // Every `<c r>` a reader walks comes through here, almost always as plain
+  // upper-case "AB12", so that shape is read off the char codes without the
+  // regex, the upper-casing and the cache lookup. Anything else, including an
+  // out-of-range reference, takes the general path and its errors.
+  let i = 0;
+  let col = 0;
+  for (let c = coord.charCodeAt(0); c >= 65 /* A */ && c <= 90 /* Z */ && i < 3; c = coord.charCodeAt(++i)) {
+    col = col * 26 + (c - 64);
+  }
+  const lead = coord.charCodeAt(i);
+  if (i > 0 && col <= MAX_COL && lead >= 49 /* 1 */ && lead <= 57 /* 9 */ && coord.length - i <= 7) {
+    let row = 0;
+    for (; i < coord.length; i++) {
+      const d = coord.charCodeAt(i);
+      if (d < 48 /* 0 */ || d > 57 /* 9 */) break;
+      row = row * 10 + (d - 48);
+    }
+    if (i === coord.length && row <= MAX_ROW) return { col, row };
+  }
   const c = coordinateFromString(coord);
   return { col: columnIndexFromLetter(c.column), row: c.row };
 }
diff --git a/src/xml/iterparse.ts b/src/xml/iterparse.ts
index 83eb44b4..f6eadb13 100644
--- a/src/xml/iterparse.ts
+++ b/src/xml/iterparse.ts
@@ -14,8 +14,8 @@
 // the prescan reads.
 
 import { SaxesParser } from 'saxes';
-import { OpenXmlSchemaError } from '../utils/exceptions.js';
 import { qname } from './namespaces.js';
+import { buildAttrsClark, feedSax } from './sax-feed.js';
 
 export type SaxEvent =
   | { kind: 'start'; name: string; attrs: Record<string, string> }
@@ -29,169 +29,13 @@ export type SaxEvent =
  */
 export type SaxInput = Uint8Array | string | ReadableStream<Uint8Array>;
 
-/**
- * Recognize declarations only in the prologue, skipping comments and processing
- * instructions. State spans chunks, but retained text is at most one keyword or
- * terminator. Once a root tag begins, saxes handles all remaining syntax checks.
- */
-const makeDtdScanner = (): ((chunk: string) => void) => {
-  let state: 'prologue' | 'markup' | 'comment' | 'pi' | 'done' = 'prologue';
-  let token = '';
-  return (chunk) => {
-    for (const char of chunk) {
-      if (state === 'done') return;
-      if (state === 'comment' || state === 'pi') {
-        const terminator = state === 'comment' ? '-->' : '?>';
-        token = (token + char).slice(-terminator.length);
-        if (token === terminator) {
-          state = 'prologue';
-          token = '';
-        }
-      } else if (state === 'prologue') {
-        if (char === '<') {
-          state = 'markup';
-          token = char;
-        }
-      } else {
-        token += char;
-        if (token === '<!--' || token === '<?') {
-          state = token === '<!--' ? 'comment' : 'pi';
-          token = '';
-        } else if (/^<!DOCTYPE[ \t\r\n]$/.test(token)) {
-          throw new OpenXmlSchemaError('DTD declarations are not permitted in OOXML payloads');
-        } else if (/^<!ENTITY[ \t\r\n]$/.test(token)) {
-          throw new OpenXmlSchemaError('Entity declarations are not permitted in OOXML payloads');
-        } else if (!'<!--'.startsWith(token) && !'<!DOCTYPE'.startsWith(token) && !'<!ENTITY'.startsWith(token)) {
-          // A root name starts here (or invalid markup, which saxes rejects).
-          state = 'done';
-          token = '';
-        }
-      }
-    }
-  };
-};
-
-const isReadableStream = (v: unknown): v is ReadableStream<Uint8Array> => {
-  return typeof v === 'object' && v !== null && typeof (v as ReadableStream).getReader === 'function';
-};
-
-const decoder = (): TextDecoder => new TextDecoder('utf-8', { fatal: false });
-
-/**
- * Feed size, in code units. saxes runs its handlers synchronously inside
- * `write()`, so one `write()` queues every event its argument produces before
- * the consumer sees any of them. Capping the argument caps the queue.
- *
- * This bounds every input shape, including a `ReadableStream`, whose upstream
- * chunk size is not ours to choose: the zip reader pushes 64 KB of *compressed*
- * bytes per pull, and worksheet XML inflates roughly sevenfold, so its chunks
- * arrive around 450 KB.
- */
-const FEED_CHUNK_SIZE = 64 * 1024;
-
-/**
- * Split text that exceeds the feed size. Boundaries fall on arbitrary offsets,
- * which is safe because saxes holds back a lone high surrogate at the end of a
- * `write()` and rejoins it with the next one, so a split codepoint still
- * surfaces as a single text event.
- */
-function* atFeedSize(text: string): IterableIterator<string> {
-  if (text.length === 0) return;
-  if (text.length <= FEED_CHUNK_SIZE) {
-    yield text;
-    return;
-  }
-  for (let i = 0; i < text.length; i += FEED_CHUNK_SIZE) {
-    yield text.slice(i, i + FEED_CHUNK_SIZE);
-  }
-}
-
-/**
- * Decode bytes in feed-sized slices. Slicing before the decode rather than
- * after it also bounds the decoder's output string, which matters when the
- * producer hands over a whole part at once. UTF-8 never expands, so a slice of
- * FEED_CHUNK_SIZE bytes decodes to at most that many code units and needs no
- * second split.
- *
- * `stream: true` holds back a codepoint split across a slice boundary instead
- * of emitting a replacement character for each half.
- */
-function* decodeAtFeedSize(bytes: Uint8Array, td: TextDecoder): IterableIterator<string> {
-  for (let i = 0; i < bytes.byteLength; i += FEED_CHUNK_SIZE) {
-    const text = td.decode(bytes.subarray(i, Math.min(i + FEED_CHUNK_SIZE, bytes.byteLength)), { stream: true });
-    if (text.length > 0) yield text;
-  }
-}
-
-/** Decode any supported input into a sequence of feed-sized text chunks. */
-async function* decodedChunks(input: SaxInput): AsyncIterableIterator<string> {
-  if (typeof input === 'string') {
-    yield* atFeedSize(input);
-    return;
-  }
-  const td = decoder();
-  if (input instanceof Uint8Array) {
-    yield* decodeAtFeedSize(input, td);
-  } else if (isReadableStream(input)) {
-    const reader = input.getReader();
-    try {
-      for (;;) {
-        const { done, value } = await reader.read();
-        if (done) break;
-        yield* decodeAtFeedSize(value, td);
-      }
-    } finally {
-      // Consumers abandon the iteration routinely (`iterRows({ maxRow })`
-      // returns as soon as the band ends). Without this the source stays
-      // locked and its `cancel()` never runs, which is what releases the zip
-      // reader's inflate state. A cancel that rejects is cleanup on a stream
-      // nobody will read again, and must not mask why we left the loop.
-      await reader.cancel().catch(() => {});
-      reader.releaseLock();
-    }
-  } else {
-    throw new OpenXmlSchemaError('iterParse: unsupported input type');
-  }
-  const tail = td.decode();
-  if (tail.length > 0) yield tail;
-}
-
-interface SaxesOpenTag {
-  name: string;
-  uri: string;
-  local: string;
-  prefix: string;
-  attributes: Record<string, { value: string; uri: string; local: string; prefix: string }>;
-  isSelfClosing?: boolean;
-}
-
-interface SaxesCloseTag {
-  name: string;
-  uri: string;
-  local: string;
-  prefix: string;
-}
-
-const buildAttrsClark = (attrs: SaxesOpenTag['attributes']): Record<string, string> => {
-  const out: Record<string, string> = {};
-  for (const [, info] of Object.entries(attrs)) {
-    // saxes already resolved the namespace when xmlns: true is set; raw xmlns /
-    // xmlns:* declarations have prefix='xmlns' (or local==='xmlns' when
-    // default) and we drop those — they're rebuilt by the serializer.
-    if (info.prefix === 'xmlns' || (info.prefix === '' && info.local === 'xmlns')) continue;
-    const key = qname(info.uri, info.local);
-    out[key] = info.value;
-  }
-  return out;
-};
-
 /**
  * Parse the input as a stream of SAX events. Element / attribute names are
  * returned in Clark notation (`{ns}local`).
  */
 export async function* iterParse(input: SaxInput): AsyncIterableIterator<SaxEvent> {
-  // Set up the parser. xmlns: true gives us resolved {uri, local, prefix} on
-  // every open / close tag and on every attribute.
+  // xmlns: true gives us resolved {uri, local, prefix} on every open / close
+  // tag and on every attribute.
   const parser = new SaxesParser({ xmlns: true, fragment: false });
 
   // Head-pointer ring instead of Array#shift: each saxes write() can produce
@@ -203,20 +47,11 @@ export async function* iterParse(input: SaxInput): AsyncIterableIterator<SaxEven
   // which is what keeps the queue bounded on a multi-GB sheet.
   let queue: SaxEvent[] = [];
   let head = 0;
-  let pending: Error | undefined;
 
-  parser.on('error', (err: Error) => {
-    // saxes reports syntax errors as plain Error; consumers of this library
-    // only ever see OpenXmlError subclasses.
-    pending = new OpenXmlSchemaError(`Malformed XML: ${err.message}`, { cause: err });
-  });
-  parser.on('doctype', () => {
-    pending = new OpenXmlSchemaError('DTD declarations are not permitted in OOXML payloads');
-  });
-  parser.on('opentag', (node: SaxesOpenTag) => {
+  parser.on('opentag', (node) => {
     queue.push({ kind: 'start', name: qname(node.uri, node.local), attrs: buildAttrsClark(node.attributes) });
   });
-  parser.on('closetag', (node: SaxesCloseTag) => {
+  parser.on('closetag', (node) => {
     queue.push({ kind: 'end', name: qname(node.uri, node.local) });
   });
   const pushText = (text: string): void => {
@@ -241,19 +76,5 @@ export async function* iterParse(input: SaxInput): AsyncIterableIterator<SaxEven
     }
   };
 
-  const feed = (chunk: string): void => {
-    parser.write(chunk);
-    if (pending !== undefined) throw pending;
-  };
-
-  const scanForDtd = makeDtdScanner();
-  for await (const chunk of decodedChunks(input)) {
-    scanForDtd(chunk);
-    feed(chunk);
-    yield* drain();
-  }
-
-  parser.close();
-  if (pending !== undefined) throw pending;
-  yield* drain();
+  for await (const _ of feedSax(input, parser)) yield* drain();
 }
diff --git a/src/xml/sax-feed.ts b/src/xml/sax-feed.ts
new file mode 100644
index 00000000..b4b23be2
--- /dev/null
+++ b/src/xml/sax-feed.ts
@@ -0,0 +1,187 @@
+// The saxes driver behind `iterParse` and the streaming row walk: input
+// decoding in bounded feeds, the DTD prescan, and saxes errors rewrapped as
+// `OpenXmlSchemaError`.
+//
+// Internal on purpose. Its signatures name saxes types, and a public
+// declaration that imports them hands consumers saxes' own `.d.ts`, which
+// does not type-check under `skipLibCheck: false`. Keep it out of every
+// subpath's declaration graph.
+
+import type { SaxesAttributeNS, SaxesParser } from 'saxes';
+import { OpenXmlSchemaError } from '../utils/exceptions.js';
+import type { SaxInput } from './iterparse.js';
+import { qname } from './namespaces.js';
+
+/**
+ * Recognize declarations only in the prologue, skipping comments and processing
+ * instructions. State spans chunks, but retained text is at most one keyword or
+ * terminator. Once a root tag begins, saxes handles all remaining syntax checks.
+ */
+const makeDtdScanner = (): ((chunk: string) => void) => {
+  let state: 'prologue' | 'markup' | 'comment' | 'pi' | 'done' = 'prologue';
+  let token = '';
+  return (chunk) => {
+    for (const char of chunk) {
+      if (state === 'done') return;
+      if (state === 'comment' || state === 'pi') {
+        const terminator = state === 'comment' ? '-->' : '?>';
+        token = (token + char).slice(-terminator.length);
+        if (token === terminator) {
+          state = 'prologue';
+          token = '';
+        }
+      } else if (state === 'prologue') {
+        if (char === '<') {
+          state = 'markup';
+          token = char;
+        }
+      } else {
+        token += char;
+        if (token === '<!--' || token === '<?') {
+          state = token === '<!--' ? 'comment' : 'pi';
+          token = '';
+        } else if (/^<!DOCTYPE[ \t\r\n]$/.test(token)) {
+          throw new OpenXmlSchemaError('DTD declarations are not permitted in OOXML payloads');
+        } else if (/^<!ENTITY[ \t\r\n]$/.test(token)) {
+          throw new OpenXmlSchemaError('Entity declarations are not permitted in OOXML payloads');
+        } else if (!'<!--'.startsWith(token) && !'<!DOCTYPE'.startsWith(token) && !'<!ENTITY'.startsWith(token)) {
+          // A root name starts here (or invalid markup, which saxes rejects).
+          state = 'done';
+          token = '';
+        }
+      }
+    }
+  };
+};
+
+const isReadableStream = (v: unknown): v is ReadableStream<Uint8Array> => {
+  return typeof v === 'object' && v !== null && typeof (v as ReadableStream).getReader === 'function';
+};
+
+const decoder = (): TextDecoder => new TextDecoder('utf-8', { fatal: false });
+
+/**
+ * Feed size, in code units. saxes runs its handlers synchronously inside
+ * `write()`, so one `write()` queues every event its argument produces before
+ * the consumer sees any of them. Capping the argument caps the queue.
+ *
+ * This bounds every input shape, including a `ReadableStream`, whose upstream
+ * chunk size is not ours to choose: the zip reader pushes 64 KB of *compressed*
+ * bytes per pull, and worksheet XML inflates roughly sevenfold, so its chunks
+ * arrive around 450 KB.
+ */
+const FEED_CHUNK_SIZE = 64 * 1024;
+
+/**
+ * Split text that exceeds the feed size. Boundaries fall on arbitrary offsets,
+ * which is safe because saxes holds back a lone high surrogate at the end of a
+ * `write()` and rejoins it with the next one, so a split codepoint still
+ * surfaces as a single text event.
+ */
+function* atFeedSize(text: string): IterableIterator<string> {
+  if (text.length === 0) return;
+  if (text.length <= FEED_CHUNK_SIZE) {
+    yield text;
+    return;
+  }
+  for (let i = 0; i < text.length; i += FEED_CHUNK_SIZE) {
+    yield text.slice(i, i + FEED_CHUNK_SIZE);
+  }
+}
+
+/**
+ * Decode bytes in feed-sized slices. Slicing before the decode rather than
+ * after it also bounds the decoder's output string, which matters when the
+ * producer hands over a whole part at once. UTF-8 never expands, so a slice of
+ * FEED_CHUNK_SIZE bytes decodes to at most that many code units and needs no
+ * second split.
+ *
+ * `stream: true` holds back a codepoint split across a slice boundary instead
+ * of emitting a replacement character for each half.
+ */
+function* decodeAtFeedSize(bytes: Uint8Array, td: TextDecoder): IterableIterator<string> {
+  for (let i = 0; i < bytes.byteLength; i += FEED_CHUNK_SIZE) {
+    const text = td.decode(bytes.subarray(i, Math.min(i + FEED_CHUNK_SIZE, bytes.byteLength)), { stream: true });
+    if (text.length > 0) yield text;
+  }
+}
+
+/** Decode any supported input into a sequence of feed-sized text chunks. */
+async function* decodedChunks(input: SaxInput): AsyncIterableIterator<string> {
+  if (typeof input === 'string') {
+    yield* atFeedSize(input);
+    return;
+  }
+  const td = decoder();
+  if (input instanceof Uint8Array) {
+    yield* decodeAtFeedSize(input, td);
+  } else if (isReadableStream(input)) {
+    const reader = input.getReader();
+    try {
+      for (;;) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        yield* decodeAtFeedSize(value, td);
+      }
+    } finally {
+      // Consumers abandon the iteration routinely (`iterRows({ maxRow })`
+      // returns as soon as the band ends). Without this the source stays
+      // locked and its `cancel()` never runs, which is what releases the zip
+      // reader's inflate state. A cancel that rejects is cleanup on a stream
+      // nobody will read again, and must not mask why we left the loop.
+      await reader.cancel().catch(() => {});
+      reader.releaseLock();
+    }
+  } else {
+    throw new OpenXmlSchemaError('iterParse: unsupported input type');
+  }
+  const tail = td.decode();
+  if (tail.length > 0) yield tail;
+}
+
+export const buildAttrsClark = (attrs: Record<string, SaxesAttributeNS>): Record<string, string> => {
+  const out: Record<string, string> = {};
+  for (const [, info] of Object.entries(attrs)) {
+    // saxes already resolved the namespace when xmlns: true is set; raw xmlns /
+    // xmlns:* declarations have prefix='xmlns' (or local==='xmlns' when
+    // default) and we drop those — they're rebuilt by the serializer.
+    if (info.prefix === 'xmlns' || (info.prefix === '' && info.local === 'xmlns')) continue;
+    const key = qname(info.uri, info.local);
+    out[key] = info.value;
+  }
+  return out;
+};
+
+/**
+ * Drive `parser` over `input`, pausing after every feed so the caller can hand
+ * on whatever its handlers collected from that feed. Handlers registered on
+ * the parser run synchronously inside each feed, which is what lets a hot
+ * consumer skip the per-event allocation and async step of `iterParse`.
+ *
+ * Installs the `error` and `doctype` handlers itself: every caller needs the
+ * same refusal of DTDs and the same `OpenXmlSchemaError` wrapping of saxes'
+ * plain `Error`.
+ */
+export async function* feedSax(input: SaxInput, parser: SaxesParser): AsyncIterableIterator<void> {
+  let pending: Error | undefined;
+  parser.on('error', (err: Error) => {
+    // saxes reports syntax errors as plain Error; consumers of this library
+    // only ever see OpenXmlError subclasses.
+    pending = new OpenXmlSchemaError(`Malformed XML: ${err.message}`, { cause: err });
+  });
+  parser.on('doctype', () => {
+    pending = new OpenXmlSchemaError('DTD declarations are not permitted in OOXML payloads');
+  });
+
+  const scanForDtd = makeDtdScanner();
+  for await (const chunk of decodedChunks(input)) {
+    scanForDtd(chunk);
+    parser.write(chunk);
+    if (pending !== undefined) throw pending;
+    yield;
+  }
+
+  parser.close();
+  if (pending !== undefined) throw pending;
+  yield;
+}
diff --git a/tests/perf/iter-rows-throughput.test.ts b/tests/perf/iter-rows-throughput.test.ts
new file mode 100644
index 00000000..cc6cd086
--- /dev/null
+++ b/tests/perf/iter-rows-throughput.test.ts
@@ -0,0 +1,96 @@
+// Throughput gate for `loadWorkbookStream`'s `iterRows` on a wide sheet whose
+// cells are almost all empty but styled (`<c r="X1" s="n"/>`), the shape
+// business exports tend to have. Such a sheet is nearly all SAX events and
+// almost no values, so any per-event overhead in the row walk shows up here
+// at full strength (#302).
+//
+// Excluded from the default `pnpm test` run (see vitest.config.ts). Run
+// explicitly:
+//
+//     pnpm test:perf
+//     PERF_GATE=1 pnpm test:perf  # also assert the ratio
+//
+// The gate compares `iterRows` against `loadWorkbook` over the same bytes
+// rather than against a cells/s floor, so the machine divides out. Holding
+// one row at a time has no reason to be slower than building the whole
+// worksheet model: before #302 the walk took 1.5–3× as long as the load, and
+// after it a fraction.
+
+import { describe, expect, it } from 'vitest';
+import { loadWorkbook } from '../../src/io/load.js';
+import { fromBuffer, toBuffer } from '../../src/io/node.js';
+import { loadWorkbookStream } from '../../src/streaming/read-only.js';
+import { createWriteOnlyWorkbook } from '../../src/streaming/write-only.js';
+import { makeAlignment } from '../../src/styles/alignment.js';
+
+const ROWS = 5_000;
+const COLS = 227;
+const TOTAL_CELLS = ROWS * COLS;
+// Columns that hold a value; every other column is a styled empty cell.
+const VALUE_COLS = new Set([0, 1, 3, 11, 89]);
+
+const PERF_GATE = process.env['PERF_GATE'] === '1';
+const MAX_ITER_TO_LOAD_RATIO = 1;
+
+const ITERATIONS = 3;
+
+const buildArchive = async (): Promise<Uint8Array> => {
+  const sink = toBuffer();
+  const wb = await createWriteOnlyWorkbook(sink);
+  const ws = await wb.addWorksheet('Data');
+  const style = { alignment: makeAlignment({ vertical: 'center', horizontal: 'left' }) };
+  for (let r = 1; r <= ROWS; r++) {
+    const row = Array.from({ length: COLS }, (_, c) => ({
+      value: VALUE_COLS.has(c) ? (c === 1 ? `S${r}` : r + c) : null,
+      style,
+    }));
+    await ws.appendRow(row);
+  }
+  await ws.close();
+  await wb.finalize();
+  return sink.result();
+};
+
+const timeIterRows = async (bytes: Uint8Array): Promise<{ seconds: number; cells: number }> => {
+  const t0 = performance.now();
+  const wb = await loadWorkbookStream(fromBuffer(bytes));
+  let cells = 0;
+  for await (const row of wb.openWorksheet('Data').iterRows()) cells += row.length;
+  await wb.close();
+  return { seconds: (performance.now() - t0) / 1000, cells };
+};
+
+const timeLoad = async (bytes: Uint8Array): Promise<number> => {
+  const t0 = performance.now();
+  await loadWorkbook(fromBuffer(bytes));
+  return (performance.now() - t0) / 1000;
+};
+
+describe('perf: iterRows over styled empty cells', () => {
+  it(
+    `walks ${ROWS} × ${COLS} = ${TOTAL_CELLS.toLocaleString()} mostly-empty styled cells no slower than loadWorkbook`,
+    async () => {
+      const bytes = await buildArchive();
+      // Warmup, discarded: the first pass pays JIT compile for both paths.
+      await timeIterRows(bytes);
+      await timeLoad(bytes);
+      const iterRuns: Array<{ seconds: number; cells: number }> = [];
+      const loadRuns: number[] = [];
+      for (let i = 0; i < ITERATIONS; i++) {
+        iterRuns.push(await timeIterRows(bytes));
+        loadRuns.push(await timeLoad(bytes));
+      }
+      const bestIter = Math.min(...iterRuns.map((r) => r.seconds));
+      const bestLoad = Math.min(...loadRuns);
+      const ratio = bestIter / bestLoad;
+      process.stderr.write(
+        `[perf] ${TOTAL_CELLS.toLocaleString()} styled cells → iterRows best ${bestIter.toFixed(2)}s, loadWorkbook best ${bestLoad.toFixed(2)}s, ratio ${ratio.toFixed(2)} (max ${MAX_ITER_TO_LOAD_RATIO})\n`,
+      );
+
+      // A walk that dropped cells would post a flattering time.
+      for (const run of iterRuns) expect(run.cells).toBe(TOTAL_CELLS);
+      if (PERF_GATE) expect(ratio).toBeLessThanOrEqual(MAX_ITER_TO_LOAD_RATIO);
+    },
+    /* timeout */ 10 * 60_000,
+  );
+});

From 9a79c0d81364da90e6f56b272fa83b89bfffc3d8 Mon Sep 17 00:00:00 2001
From: baseballyama <xydybaseball@gmail.com>
Date: Sun, 11 Oct 2026 15:56:14 +0900
Subject: [PATCH 2/2] test(conformance): point the cdata mutation at the
 streaming row walk

The corpus case that guards CDATA reads through loadWorkbookStream, which
no longer goes through iterParse, so the mutant has to sit on the handler
the row walk registers itself.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0142ArZjzXh8UP4dVS623qG3
---
 tests/conformance/mutations.json | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/tests/conformance/mutations.json b/tests/conformance/mutations.json
index 3842270d..e3387631 100644
--- a/tests/conformance/mutations.json
+++ b/tests/conformance/mutations.json
@@ -22,8 +22,8 @@
   {
     "id": "cdata-text",
     "regression": "XML character data preservation",
-    "file": "src/xml/iterparse.ts",
-    "before": "parser.on('cdata', pushText);",
+    "file": "src/streaming/read-only.ts",
+    "before": "parser.on('cdata', onText);",
     "after": "parser.on('cdata', () => {});",
     "tests": [
       "tests/conformance/corpus.test.ts"