@shbernal/ts-xlsx 1.0.0

package/dist/io/xlsx/pivot-read.js

@@ -0,0 +1,134 @@
+// Reading a pivot table back from its OOXML parts — the inverse of `pivot.ts`.
+//
+// A written pivot round-trips today by byte-preservation: the reader keeps the pivot parts verbatim
+// and re-emits them. That keeps the file faithful, but leaves the pivot opaque to the model — a
+// `.model` copy cannot carry a pivot it cannot see. This module reconstructs the *semantic* shape of
+// a pivot (its source, field roles, value field, and aggregation) from the `pivotTableDefinition`
+// and its `pivotCacheDefinition`, so a loaded pivot becomes inspectable data rather than an opaque
+// blob.
+//
+// Read leniently: these parts describe a file that already exists, so a missing or unrecognised
+// attribute yields a sensible default rather than a throw — the strict invariants belong on the
+// authoring path (`core/pivot-table.ts`), not here. A hostile part therefore degrades to an
+// incomplete model; it never crashes the reader.
+import { pivotMetricFromSubtotal, } from "../../core/pivot-table.js";
+import { localName, parseXml } from "../../xml/xml-read.js";
+/** Reconstruct a pivot's semantic model from its two definition parts. The records part is not
+ * consulted: the cache's field catalogue and the table's field roles fully describe the pivot's
+ * shape, and the aggregated values are Excel's to compute on refresh. */
+export function parsePivotTable(tableXml, cacheXml) {
+    const { fields, source } = parsePivotCacheDefinition(cacheXml);
+    const def = parsePivotTableDefinition(tableXml);
+    return {
+        name: def.name,
+        cacheId: def.cacheId,
+        source,
+        fields,
+        rowFields: def.rowFields,
+        columnFields: def.columnFields,
+        valueField: def.valueField,
+        valueFieldName: fields[def.valueField]?.name ?? '',
+        valueCaption: def.valueCaption,
+        metric: def.metric,
+    };
+}
+/** The field catalogue and worksheet source from a `pivotCacheDefinition`. Fields are collected in
+ * document order — the order a table's `fld`/`x` indices address them by. */
+function parsePivotCacheDefinition(cacheXml) {
+    const fields = [];
+    // A worksheet source is the assumed default until proven otherwise: it is what our writer emits and
+    // the overwhelmingly common shape, and its `<worksheetSource>` child fills in the coordinates. A
+    // `<cacheSource type>` we recognise overrides the kind; an unrecognised one degrades to `unknown`.
+    let source = { kind: 'worksheet', sheet: '', ref: '' };
+    parseXml(cacheXml, {
+        onOpen(name, attrs) {
+            const local = localName(name);
+            if (local === 'cacheField' && attrs.name !== undefined) {
+                fields.push({ name: attrs.name });
+            }
+            else if (local === 'cacheSource') {
+                source = { ...source, kind: sourceKind(attrs.type) };
+            }
+            else if (local === 'worksheetSource') {
+                source = { ...source, sheet: attrs.sheet ?? '', ref: attrs.ref ?? '' };
+            }
+        },
+    });
+    return { fields, source };
+}
+/** The layout half of a pivot: its name, cache id, axis field roles, and the single value field.
+ * `<field x>` appears identically inside `<rowFields>` and `<colFields>`, so the current container is
+ * tracked to route each into the right axis. Only the first `<dataField>` is modeled — the authoring
+ * model supports one value field — and any further ones are ignored rather than rejected. */
+function parsePivotTableDefinition(tableXml) {
+    let name = '';
+    let cacheId = '';
+    const rowFields = [];
+    const columnFields = [];
+    let valueField = -1;
+    let valueCaption = '';
+    let metric = 'sum';
+    let seenDataField = false;
+    let axis = null;
+    parseXml(tableXml, {
+        onOpen(elementName, attrs) {
+            switch (localName(elementName)) {
+                case 'pivotTableDefinition':
+                    name = attrs.name ?? '';
+                    cacheId = attrs.cacheId ?? '';
+                    break;
+                case 'rowFields':
+                    axis = 'row';
+                    break;
+                case 'colFields':
+                    axis = 'col';
+                    break;
+                case 'field': {
+                    if (axis === null)
+                        break;
+                    const index = toIndex(attrs.x);
+                    if (index >= 0)
+                        (axis === 'row' ? rowFields : columnFields).push(index);
+                    break;
+                }
+                case 'dataField': {
+                    if (seenDataField)
+                        break;
+                    seenDataField = true;
+                    valueField = toIndex(attrs.fld);
+                    valueCaption = attrs.name ?? '';
+                    metric = pivotMetricFromSubtotal(attrs.subtotal);
+                    break;
+                }
+            }
+        },
+        onClose(elementName) {
+            const local = localName(elementName);
+            if (local === 'rowFields' || local === 'colFields')
+                axis = null;
+        },
+    });
+    return { name, cacheId, rowFields, columnFields, valueField, valueCaption, metric };
+}
+const SOURCE_KINDS = new Set([
+    'worksheet',
+    'external',
+    'consolidation',
+    'scenario',
+]);
+/** Map a `<cacheSource type>` to a known kind. Absent reads as `worksheet` (the spec default and what
+ * our writer emits); an unrecognised value reads as `unknown` rather than throwing, keeping the read
+ * lenient while still telling a consumer the declared source is not one we model. */
+function sourceKind(type) {
+    if (type === undefined)
+        return 'worksheet';
+    return SOURCE_KINDS.has(type) ? type : 'unknown';
+}
+/** Parse a non-negative field index attribute, or -1 when it is absent or not a whole number — a
+ * hostile `x="../etc"` can never become a wild array index this way. */
+function toIndex(value) {
+    if (value === undefined)
+        return -1;
+    const index = Number(value);
+    return Number.isInteger(index) && index >= 0 ? index : -1;
+}

package/dist/io/xlsx/pivot.d.ts

@@ -0,0 +1,12 @@
+import type { PivotTable } from '../../core/pivot-table.ts';
+/** The `pivotCacheDefinition` part: the source reference and the field catalogue. `r:id="rId1"`
+ * names the cache-records part through this cache's own rels part. `refreshOnLoad="1"` tells Excel to
+ * rebuild the pivot body from the cache on open, so the layout stays correct without us computing it
+ * to the pixel. `recordCount` is the number of source data rows. */
+export declare function pivotCacheDefinitionXml(table: PivotTable): string;
+/** The `pivotCacheRecords` part: one `<r>` per source data row, each cell either an index into an
+ * axis field's shared-items catalogue (`<x>`) or an inline value (`<n>`/`<s>`/`<m>`). */
+export declare function pivotCacheRecordsXml(table: PivotTable): string;
+/** The `pivotTableDefinition` part placed on the destination sheet: the field layout that binds the
+ * cache (by `cacheId`) to the row/column axes and the summed value field. */
+export declare function pivotTableXml(table: PivotTable, name: string, cacheId: string): string;

package/dist/io/xlsx/pivot.js

@@ -0,0 +1,141 @@
+// OOXML rendering for a modeled pivot table: the three parts a pivot needs — the cache definition
+// (field catalogue), the cache records (a copy of the source rows), and the pivot table definition
+// (the layout). The semantic computation lives in `core/pivot-table.ts`; this file only serialises.
+//
+// Every value that reaches an attribute is run through `escapeAttr`, so source strings carrying XML
+// specials (`Smith & Co`, `<West>`, `It's "best"`) become well-formed markup rather than corrupting
+// the package — the whole point of the shared-item escaping this module guarantees.
+import { encodeAddress } from "../../core/address.js";
+import { escapeAttr, XML_DECLARATION } from "../../xml/xml.js";
+import { RELATIONSHIPS_NS } from "../opc/namespaces.js";
+import { SPREADSHEETML_NS } from "./namespaces.js";
+// Excel's default caption prefix for each aggregation ("Sum of Amount", "Average of Amount"). A
+// metric's name is also its `subtotal` value, which is why the record key equals the enum member.
+const METRIC_CAPTIONS = {
+    sum: 'Sum',
+    count: 'Count',
+    countNums: 'Count',
+    average: 'Average',
+    max: 'Max',
+    min: 'Min',
+    product: 'Product',
+    stdDev: 'StdDev',
+    stdDevp: 'StdDevp',
+    var: 'Var',
+    varp: 'Varp',
+};
+/** The `pivotCacheDefinition` part: the source reference and the field catalogue. `r:id="rId1"`
+ * names the cache-records part through this cache's own rels part. `refreshOnLoad="1"` tells Excel to
+ * rebuild the pivot body from the cache on open, so the layout stays correct without us computing it
+ * to the pixel. `recordCount` is the number of source data rows. */
+export function pivotCacheDefinitionXml(table) {
+    const fields = table.cacheFields
+        .map((field) => {
+        const shared = field.sharedItems;
+        if (shared !== null) {
+            const items = shared.map(sharedItemXml).join('');
+            const blank = field.containsBlank ? ' containsBlank="1"' : '';
+            return (`<cacheField name="${escapeAttr(field.name)}" numFmtId="0">` +
+                `<sharedItems${blank} count="${shared.length}">${items}</sharedItems>` +
+                `</cacheField>`);
+        }
+        const blank = field.containsBlank ? ' containsBlank="1"' : '';
+        const numeric = field.numeric;
+        const descriptor = numeric === null
+            ? `<sharedItems${blank}/>`
+            : `<sharedItems containsSemiMixedTypes="0" containsString="0" containsNumber="1" ` +
+                `containsInteger="${numeric.allInteger ? 1 : 0}"${blank} ` +
+                `minValue="${numeric.min}" maxValue="${numeric.max}"/>`;
+        return `<cacheField name="${escapeAttr(field.name)}" numFmtId="0">${descriptor}</cacheField>`;
+    })
+        .join('');
+    return (XML_DECLARATION +
+        `<pivotCacheDefinition xmlns="${SPREADSHEETML_NS}" xmlns:r="${RELATIONSHIPS_NS}" r:id="rId1" refreshOnLoad="1" ` +
+        `refreshedBy="ts-xlsx" createdVersion="8" refreshedVersion="8" minRefreshableVersion="3" ` +
+        `recordCount="${table.records.length}">` +
+        `<cacheSource type="worksheet">` +
+        `<worksheetSource ref="${escapeAttr(table.sourceRef)}" sheet="${escapeAttr(table.sourceSheetName)}"/>` +
+        `</cacheSource>` +
+        `<cacheFields count="${table.cacheFields.length}">${fields}</cacheFields>` +
+        `</pivotCacheDefinition>`);
+}
+/** The `pivotCacheRecords` part: one `<r>` per source data row, each cell either an index into an
+ * axis field's shared-items catalogue (`<x>`) or an inline value (`<n>`/`<s>`/`<m>`). */
+export function pivotCacheRecordsXml(table) {
+    const rows = table.records
+        .map((record) => `<r>${record.map(recordCellXml).join('')}</r>`)
+        .join('');
+    return (XML_DECLARATION +
+        `<pivotCacheRecords xmlns="${SPREADSHEETML_NS}" xmlns:r="${RELATIONSHIPS_NS}" count="${table.records.length}">` +
+        rows +
+        `</pivotCacheRecords>`);
+}
+/** The `pivotTableDefinition` part placed on the destination sheet: the field layout that binds the
+ * cache (by `cacheId`) to the row/column axes and the summed value field. */
+export function pivotTableXml(table, name, cacheId) {
+    const rowField = table.rowFields[0];
+    const columnField = table.columnFields[0];
+    const rowGroups = table.cacheFields[rowField]?.sharedItems?.length ?? 1;
+    const columnGroups = table.cacheFields[columnField]?.sharedItems?.length ?? 1;
+    // A generous bounding box on the destination sheet: a row-label column plus one column per column
+    // group plus a grand-total column; two header rows plus one row per row group plus a grand total.
+    // Excel recomputes the exact extent from the cache on refresh, so this only has to be valid.
+    const location = `A1:${encodeAddress(2 + columnGroups, 3 + rowGroups)}`;
+    const pivotFields = table.cacheFields
+        .map((field, index) => {
+        if (table.rowFields.includes(index) || table.columnFields.includes(index)) {
+            const axis = table.rowFields.includes(index) ? 'axisRow' : 'axisCol';
+            const items = field.sharedItems ?? [];
+            const entries = `${items.map((_item, i) => `<item x="${i}"/>`).join('')}<item t="default"/>`;
+            return `<pivotField axis="${axis}" showAll="0"><items count="${items.length + 1}">${entries}</items></pivotField>`;
+        }
+        if (index === table.valueField)
+            return '<pivotField dataField="1" showAll="0"/>';
+        return '<pivotField showAll="0"/>';
+    })
+        .join('');
+    const rowFields = table.rowFields.map((index) => `<field x="${index}"/>`).join('');
+    const columnFields = table.columnFields.map((index) => `<field x="${index}"/>`).join('');
+    return (XML_DECLARATION +
+        `<pivotTableDefinition xmlns="${SPREADSHEETML_NS}" xmlns:r="${RELATIONSHIPS_NS}" name="${escapeAttr(name)}" ` +
+        `cacheId="${escapeAttr(cacheId)}" applyNumberFormats="0" applyBorderFormats="0" ` +
+        `applyFontFormats="0" applyPatternFormats="0" applyAlignmentFormats="0" ` +
+        `applyWidthHeightFormats="1" dataCaption="Values" updatedVersion="8" minRefreshableVersion="3" ` +
+        `useAutoFormatting="1" itemPrintTitles="1" createdVersion="8" indent="0" outline="1" ` +
+        `outlineData="1" multipleFieldFilters="0">` +
+        `<location ref="${location}" firstHeaderRow="1" firstDataRow="2" firstDataCol="1"/>` +
+        `<pivotFields count="${table.cacheFields.length}">${pivotFields}</pivotFields>` +
+        `<rowFields count="${table.rowFields.length}">${rowFields}</rowFields>` +
+        `<rowItems count="1"><i t="grand"><x/></i></rowItems>` +
+        `<colFields count="${table.columnFields.length}">${columnFields}</colFields>` +
+        `<colItems count="1"><i t="grand"><x/></i></colItems>` +
+        `<dataFields count="1">` +
+        dataFieldXml(table) +
+        `</dataFields>` +
+        `<pivotTableStyleInfo name="PivotStyleLight16" showRowHeaders="1" showColHeaders="1" ` +
+        `showRowStripes="0" showColStripes="0" showLastColumn="1"/>` +
+        `</pivotTableDefinition>`);
+}
+/** The `<dataField>` that names the aggregated column and selects its function. `sum` is Excel's
+ * implicit default, so its `subtotal` attribute is omitted; every other metric names itself. */
+function dataFieldXml(table) {
+    const caption = `${METRIC_CAPTIONS[table.metric]} of ${table.valueFieldName}`;
+    const subtotal = table.metric === 'sum' ? '' : ` subtotal="${table.metric}"`;
+    return (`<dataField name="${escapeAttr(caption)}" fld="${table.valueField}"${subtotal} ` +
+        `baseField="0" baseItem="0"/>`);
+}
+function sharedItemXml(item) {
+    switch (item.kind) {
+        case 'string':
+            return `<s v="${escapeAttr(item.value)}"/>`;
+        case 'number':
+            return `<n v="${item.value}"/>`;
+        case 'blank':
+            return '<m/>';
+    }
+}
+function recordCellXml(cell) {
+    if (cell.kind === 'index')
+        return `<x v="${cell.index}"/>`;
+    return sharedItemXml(cell);
+}

package/dist/io/xlsx/read-rows.d.ts

@@ -0,0 +1,85 @@
+import type { CellValue } from '../../core/value.ts';
+import { type ReadXlsxOptions, type XfStyle } from './read.ts';
+export interface ReadSheetRowsOptions extends ReadXlsxOptions {
+    /**
+     * Which worksheet to stream: its name, or its 1-based position in the workbook. Defaults to the
+     * first sheet.
+     */
+    readonly sheet?: string | number;
+}
+/**
+ * The resolved style facets of a streamed cell — its own `<c s>` cell format, flattened exactly as
+ * the buffered reader resolves it. Present only when the cell carries a format; a consumer can copy
+ * these straight onto a writer cell to preserve its look through a streaming read→write.
+ */
+export type StreamedCellStyle = XfStyle;
+/** One non-empty cell in a {@link StreamedRow}. */
+export interface StreamedCell {
+    /** 1-based column index. */
+    readonly col: number;
+    /** Canonical A1 address (`"B3"`). */
+    readonly address: string;
+    /** The decoded value — identical to what `readXlsx` would produce for the same cell. */
+    readonly value: CellValue;
+    /** The cell's resolved style facets, or absent when the cell carries no format of its own. */
+    readonly style?: StreamedCellStyle;
+}
+/** One worksheet row, as yielded by {@link readSheetRows} / {@link StreamedSheet.rows}. */
+export interface StreamedRow {
+    /** 1-based row index. */
+    readonly number: number;
+    /** Whether the row declares itself hidden. */
+    readonly hidden: boolean;
+    /** The row's non-empty cells, in column order. An empty (or purely style-only) row yields none. */
+    readonly cells: readonly StreamedCell[];
+}
+/**
+ * One worksheet, as yielded by {@link readWorkbookStream}. The sheet's {@link rows} stream one at a
+ * time; its {@link hiddenColumns} and {@link merges} are populated by that same single pass.
+ *
+ * The two summaries are resolved lazily: reading either accessor drives a full scan of the sheet if
+ * its rows have not already been consumed, so their order relative to `rows()` never matters. (When
+ * rows *are* consumed first — the streaming idiom — the accessors reuse that pass and re-scan
+ * nothing.)
+ */
+export interface StreamedSheet {
+    /** The worksheet's declared name, joined from the workbook part — never a positional placeholder. */
+    readonly name: string;
+    /** Stream this sheet's rows, one at a time, in sheet order. */
+    rows(): Generator<StreamedRow>;
+    /** 1-based indices of columns the sheet declares hidden, ascending. */
+    readonly hiddenColumns: readonly number[];
+    /** The sheet's merged ranges, as canonical A1 range strings, in declaration order. */
+    readonly merges: readonly string[];
+}
+/**
+ * Stream a worksheet's rows from an `.xlsx` package, yielding each in sheet order without building
+ * the workbook model. Only rows the sheet actually declares are yielded, and within a row only its
+ * non-empty cells — a blank or style-only cell contributes nothing, matching the intent of a data
+ * read.
+ *
+ * @param data The raw `.xlsx` bytes.
+ * @param options Sheet selector and the inflate bound (see {@link ReadSheetRowsOptions}).
+ * @throws {UnsupportedFormatError} if the input is not a readable `.xlsx` package (a legacy `.xls`, a
+ *   binary `.xlsb`, or an unrecognised/non-ZIP blob — branch on `.format`).
+ * @throws {@link PackageReadError} if the input is a ZIP that cannot be unpacked — a corrupt or
+ *   truncated archive, or one exceeding the inflate bound (a probable zip bomb).
+ * @throws {@link XlsxParseError} if the package's workbook part declares no worksheets.
+ * @throws {RangeError} / {@link AuthoringError} if `options.sheet` selects a position, or a name,
+ *   that no worksheet has.
+ */
+export declare function readSheetRows(data: Uint8Array, options?: ReadSheetRowsOptions): Generator<StreamedRow>;
+/**
+ * Stream every worksheet of an `.xlsx` package in workbook order, without building the workbook
+ * model. Each yielded {@link StreamedSheet} carries the declared sheet name and lets the caller
+ * stream that sheet's rows and read its hidden-column and merge summaries — the streaming analogue
+ * of walking `readXlsx(data).worksheets`.
+ *
+ * @param data The raw `.xlsx` bytes.
+ * @param options The inflate bound (see {@link ReadXlsxOptions}).
+ * @throws {UnsupportedFormatError} if the input is not a readable `.xlsx` package (a legacy `.xls`, a
+ *   binary `.xlsb`, or an unrecognised/non-ZIP blob — branch on `.format`).
+ * @throws {@link PackageReadError} if the input is a ZIP that cannot be unpacked — a corrupt or
+ *   truncated archive, or one exceeding the inflate bound (a probable zip bomb).
+ */
+export declare function readWorkbookStream(data: Uint8Array, options?: ReadXlsxOptions): Generator<StreamedSheet>;

package/dist/io/xlsx/read-rows.js

@@ -0,0 +1,286 @@
+// Streaming row reader: yield a worksheet's rows one at a time, without ever building the whole
+// {@link Workbook} model.
+//
+// `readXlsx` materialises every cell of every sheet as a live `Cell` object held in nested Maps —
+// fine for editing, but for a large sheet read purely to extract its data it holds the entire grid
+// in memory at once. This reader instead *pulls* the sheet's XML through `xmlEvents` and yields a
+// plain {@link StreamedRow} at each `</row>`, retaining only the row currently in hand. Peak model
+// memory is one row, not the sheet.
+//
+// Two entry points sit on the same scanner:
+//   - {@link readSheetRows} streams a single selected sheet's rows (the terse data-extraction case).
+//   - {@link readWorkbookStream} yields a {@link StreamedSheet} per worksheet in workbook order, so a
+//     caller can walk every sheet — each sheet's rows still stream one at a time.
+//
+// Scope of this slice: the package is still inflated whole (bounded by the running counter in
+// `./inflate.ts`) and shared strings / styles are read as whole parts — both are legitimately
+// document-sized and cheap. What this avoids is retaining N materialised cells. A later slice can
+// make the inflate itself per-part lazy; the pull primitive this stands on (`xmlEvents`) is the
+// same one that path will use.
+import { MAX_COLUMN } from "../../core/address.js";
+import { AuthoringError } from "../../errors.js";
+import { boolStrict, closeEmptyElements, localName, xmlEvents } from "../../xml/xml-read.js";
+import { packageAccessors } from "../opc/read-opc.js";
+import { inflateSpreadsheetPackage, unsupportedWorkbookPart } from "../opc/sniff-format.js";
+import { CellAccumulator } from "./cell-accumulator.js";
+import { XlsxParseError } from "./errors.js";
+import { DEFAULT_MAX_UNCOMPRESSED, parseRelationships, parseStyleTable, parseWorkbookSheets, resolveWorkbookPart, } from "./read.js";
+import { parseSharedStrings } from "./shared-strings-read.js";
+/**
+ * Stream a worksheet's rows from an `.xlsx` package, yielding each in sheet order without building
+ * the workbook model. Only rows the sheet actually declares are yielded, and within a row only its
+ * non-empty cells — a blank or style-only cell contributes nothing, matching the intent of a data
+ * read.
+ *
+ * @param data The raw `.xlsx` bytes.
+ * @param options Sheet selector and the inflate bound (see {@link ReadSheetRowsOptions}).
+ * @throws {UnsupportedFormatError} if the input is not a readable `.xlsx` package (a legacy `.xls`, a
+ *   binary `.xlsb`, or an unrecognised/non-ZIP blob — branch on `.format`).
+ * @throws {@link PackageReadError} if the input is a ZIP that cannot be unpacked — a corrupt or
+ *   truncated archive, or one exceeding the inflate bound (a probable zip bomb).
+ * @throws {@link XlsxParseError} if the package's workbook part declares no worksheets.
+ * @throws {RangeError} / {@link AuthoringError} if `options.sheet` selects a position, or a name,
+ *   that no worksheet has.
+ */
+export function* readSheetRows(data, options = {}) {
+    const pkg = openPackage(data, options.maxUncompressedBytes);
+    const chosen = pickSheet(pkg.sheets, options.sheet);
+    const sheetXml = pkg.sheetXml(chosen.relId);
+    // The sheet is named but its part is missing (a truncated or foreign package) — it has no rows.
+    if (sheetXml === undefined)
+        return;
+    yield* scanSheet(sheetXml, pkg.sharedStrings, pkg.xfStyles, new Set(), []);
+}
+/**
+ * Stream every worksheet of an `.xlsx` package in workbook order, without building the workbook
+ * model. Each yielded {@link StreamedSheet} carries the declared sheet name and lets the caller
+ * stream that sheet's rows and read its hidden-column and merge summaries — the streaming analogue
+ * of walking `readXlsx(data).worksheets`.
+ *
+ * @param data The raw `.xlsx` bytes.
+ * @param options The inflate bound (see {@link ReadXlsxOptions}).
+ * @throws {UnsupportedFormatError} if the input is not a readable `.xlsx` package (a legacy `.xls`, a
+ *   binary `.xlsb`, or an unrecognised/non-ZIP blob — branch on `.format`).
+ * @throws {@link PackageReadError} if the input is a ZIP that cannot be unpacked — a corrupt or
+ *   truncated archive, or one exceeding the inflate bound (a probable zip bomb).
+ */
+export function* readWorkbookStream(data, options = {}) {
+    const pkg = openPackage(data, options.maxUncompressedBytes);
+    for (const sheet of pkg.sheets) {
+        // A named sheet whose part is missing (truncated/foreign package) still surfaces — with no rows,
+        // no hidden columns, and no merges — rather than vanishing from the workbook's sheet list.
+        const xml = pkg.sheetXml(sheet.relId) ?? '';
+        yield new StreamedSheetReader(sheet.name, xml, pkg.sharedStrings, pkg.xfStyles);
+    }
+}
+function openPackage(data, maxUncompressedBytes) {
+    const cap = maxUncompressedBytes ?? DEFAULT_MAX_UNCOMPRESSED;
+    const { partText: text } = packageAccessors(inflateSpreadsheetPackage(data, cap));
+    const workbookXml = text('xl/workbook.xml');
+    // A binary `.xlsb` is a workbook this library *can* read — just not through here. Row streaming is
+    // built on the XML worksheet parser, so the binary cell table has no streaming path yet; say so,
+    // rather than reporting the format as unreadable when `readXlsx` would take the very same bytes.
+    if (workbookXml === undefined) {
+        throw unsupportedWorkbookPart(text, 'the binary .xlsb format (BIFF12) cannot be row-streamed yet; read it with readXlsx or readXlsb');
+    }
+    const sheets = parseWorkbookSheets(workbookXml);
+    const rels = parseRelationships(text('xl/_rels/workbook.xml.rels') ?? '');
+    const sharedStrings = parseSharedStrings(text('xl/sharedStrings.xml') ?? '');
+    const { cellXfs: xfStyles } = parseStyleTable(text('xl/styles.xml') ?? '');
+    return {
+        sheets,
+        sharedStrings,
+        xfStyles,
+        sheetXml(relId) {
+            const target = rels.get(relId);
+            const path = target === undefined ? undefined : resolveWorkbookPart(target);
+            return path === undefined ? undefined : text(path);
+        },
+    };
+}
+function pickSheet(sheets, selector) {
+    const first = sheets[0];
+    if (first === undefined)
+        throw new XlsxParseError('workbook names no worksheets');
+    if (selector === undefined)
+        return first;
+    if (typeof selector === 'number') {
+        const sheet = sheets[selector - 1];
+        if (sheet === undefined)
+            throw new RangeError(`no worksheet at position ${selector}`);
+        return sheet;
+    }
+    const sheet = sheets.find((candidate) => candidate.name === selector);
+    if (sheet === undefined)
+        throw new AuthoringError(`no worksheet named ${JSON.stringify(selector)}`);
+    return sheet;
+}
+// A single worksheet exposed by readWorkbookStream. Its rows() re-scans on each call (a fresh pass,
+// so it is safely re-iterable); the hidden-column and merge accessors reuse a completed scan or, if
+// the rows were never drained, drive one of their own. The hidden/merge state is filled in by the
+// same scanSheet pass that yields the rows.
+class StreamedSheetReader {
+    name;
+    #xml;
+    #sharedStrings;
+    #xfStyles;
+    #hiddenColumns = new Set();
+    #merges = [];
+    #scanned = false;
+    constructor(name, xml, sharedStrings, xfStyles) {
+        this.name = name;
+        this.#xml = xml;
+        this.#sharedStrings = sharedStrings;
+        this.#xfStyles = xfStyles;
+    }
+    *rows() {
+        this.#hiddenColumns = new Set();
+        this.#merges = [];
+        this.#scanned = false;
+        yield* scanSheet(this.#xml, this.#sharedStrings, this.#xfStyles, this.#hiddenColumns, this.#merges);
+        this.#scanned = true;
+    }
+    get hiddenColumns() {
+        this.#ensureScanned();
+        return [...this.#hiddenColumns].sort((a, b) => a - b);
+    }
+    get merges() {
+        this.#ensureScanned();
+        return this.#merges;
+    }
+    // Drain a scan purely for its summaries when the caller reads them without (or before) iterating
+    // rows. A completed row iteration already set #scanned, so this re-scans nothing in the common
+    // streaming idiom.
+    #ensureScanned() {
+        if (this.#scanned)
+            return;
+        for (const _row of this.rows()) {
+            // The rows themselves are irrelevant here — we only want the hidden/merge side effects.
+        }
+    }
+}
+// A formatted-but-empty `<c/>` is expanded to open+close so it finalises once on close, matching
+// the buffered reader; the text-bearing `<f/>`/`<v/>`/`<t/>` are excluded so an empty one never
+// commits (their close captures text, which an empty tag has none of).
+const CELL_EMPTY_CLOSE = new Set(['c']);
+// Pull the sheet XML through the event stream, yielding a StreamedRow at each `</row>`, while
+// recording the sheet's hidden columns (from `<col hidden>`, before <sheetData>) and merged ranges
+// (from `<mergeCells>`, after <sheetData>) into the caller-supplied collectors. The cell state
+// mirrors the buffered reader's `parseWorksheet` (same self-closing-`<c/>` handling, same capture
+// flags), but commits into a row buffer that is handed off and discarded per row rather than into a
+// persistent Worksheet — that hand-off is what bounds retained memory to one row.
+function* scanSheet(xml, sharedStrings, xfStyles, hiddenColumns, merges) {
+    let rowNumber = 0;
+    let lastRow = 0;
+    let rowHidden = false;
+    let cells = [];
+    // The in-flight `<c>`, gathered exactly as the buffered reader gathers it. This reader drives the
+    // same beginCell/setFormula/setValue/appendText methods, then takes only the cell's plain decoded
+    // value (via decode) — never the shared-formula / data-table resolution the buffered finalize adds,
+    // which a data read does not want. Rich `<r>` runs are deliberately not opened here, so a rich
+    // inline string flattens to its concatenated text as a streamed value always has.
+    const cell = new CellAccumulator();
+    let inInlineString = false;
+    let capture = false;
+    let text = '';
+    const finalizeCell = () => {
+        if (cell.ref === '' || cell.col < 0)
+            return;
+        const style = cell.styleIndex >= 0 ? xfStyles[cell.styleIndex] : undefined;
+        const value = cell.decode(sharedStrings, style);
+        // A blank or purely style-only cell decodes to null; a data read wants only cells that carry
+        // something (a formula object, an empty string, a false, and a 0 all count — only null drops).
+        if (value !== null) {
+            const { col, ref } = cell;
+            cells.push(style ? { col, address: ref, value, style } : { col, address: ref, value });
+        }
+    };
+    for (const event of closeEmptyElements(xmlEvents(xml), CELL_EMPTY_CLOSE)) {
+        if (event.kind === 'text') {
+            if (capture)
+                text += event.text;
+            continue;
+        }
+        if (event.kind === 'open') {
+            const local = localName(event.name);
+            text = '';
+            capture = false;
+            switch (local) {
+                case 'row': {
+                    const declared = Number(event.attrs.r);
+                    rowNumber = Number.isInteger(declared) && declared >= 1 ? declared : lastRow + 1;
+                    lastRow = rowNumber;
+                    rowHidden = boolStrict(event.attrs.hidden);
+                    cells = [];
+                    break;
+                }
+                case 'col':
+                    collectHiddenColumn(event.attrs, hiddenColumns);
+                    break;
+                case 'mergeCell':
+                    if (event.attrs.ref !== undefined)
+                        merges.push(event.attrs.ref);
+                    break;
+                case 'c':
+                    cell.beginCell(event.attrs);
+                    break;
+                case 'is':
+                    inInlineString = true;
+                    cell.beginInlineString();
+                    break;
+                case 'f':
+                    capture = true;
+                    cell.beginFormula(event.attrs, event.selfClosing);
+                    break;
+                case 'v':
+                case 't':
+                    capture = true;
+                    break;
+                default:
+                    break;
+            }
+            if (event.selfClosing && (local === 'f' || local === 'v'))
+                capture = false;
+            continue;
+        }
+        // close
+        const local = localName(event.name);
+        switch (local) {
+            case 'f':
+                cell.setFormula(text);
+                break;
+            case 'v':
+                cell.setValue(text);
+                break;
+            case 't':
+                cell.appendText(text, inInlineString);
+                break;
+            case 'is':
+                inInlineString = false;
+                break;
+            case 'c':
+                finalizeCell();
+                break;
+            case 'row':
+                yield { number: rowNumber, hidden: rowHidden, cells };
+                break;
+            default:
+                break;
+        }
+        capture = false;
+    }
+}
+// Record the hidden columns a `<col min max hidden>` element declares. The span is clamped to the
+// format's column ceiling and gathered into a Set, so even a hostile file full of full-width hidden
+// spans can add at most MAX_COLUMN distinct entries — never an unbounded allocation.
+function collectHiddenColumn(attrs, hiddenColumns) {
+    if (attrs.hidden !== '1' && attrs.hidden !== 'true')
+        return;
+    const min = Number(attrs.min);
+    const max = Number(attrs.max);
+    if (!Number.isInteger(min) || !Number.isInteger(max) || min < 1)
+        return;
+    const last = Math.min(max, MAX_COLUMN);
+    for (let index = min; index <= last; index++)
+        hiddenColumns.add(index);
+}