@shbernal/ts-xlsx 3.0.0 → 3.1.0

package/dist/io/xlsx/worksheet-xml.js

@@ -1,57 +1,25 @@
-import { decodeRange, encodeAddress } from '../../core/address.js';
-import { cellHasOwnStyle } from '../../core/cell.js';
-import { DEFAULT_DATE_NUMFMT, dateToSerial } from '../../core/date.js';
-import { mangleFormula } from '../../core/formula.js';
-import { NAMED_STYLE_ID } from '../../core/internal.js';
-import { CELL_STYLE_FACETS, pickStyleFacets } from '../../core/style.js';
-import { detectValueType, isDataTableFormulaValue, isErrorValue, isFormulaValue, isHyperlinkValue, isRichTextValue, isSharedFormulaValue, } from '../../core/value.js';
-import { AuthoringError, InternalError } from '../../errors.js';
-import { assertWritableNumber, escapeAttr, escapeSpreadsheetText, escapeText, numberText, textAttr, textElement, XML_DECLARATION, } from '../../xml/xml.js';
+import { decodeRange, encodeRect } from '../../core/address.js';
+import { pickStyleFacets } from '../../core/style.js';
+import { AuthoringError, InternalError, quoted } from '../../errors.js';
+import { escapeAttr, numberText, XML_DECLARATION } from '../../xml/xml.js';
 import { relationship, relationshipsPart } from '../opc/rels.js';
-import { conditionalFormattingsExtXml, conditionalFormattingsXml } from './conditional-formatting.js';
+import { conditionalFormattingsExtXml, conditionalFormattingsXml, dataBarExtLinks, } from './conditional-formatting.js';
 import { dataValidationsExtXml, dataValidationsXml } from './data-validation.js';
-import { hyperlinksXml } from './hyperlinks.js';
+import { hyperlinksXml, isExternalHyperlink } from './hyperlinks.js';
 import { SLICER_LIST_EXT_URI } from './namespaces.js';
 import { commentsPart, drawingPart, mediaPart, pivotTablePart, printerSettingsPart, tablePart, targetFromWorksheet, threadedCommentsPart, vmlDrawingPart, } from './part-names.js';
 import { NS, REL } from './relationships.js';
-import { richTextRunsXml } from './rich-text.js';
+import { assertWritableLevel, buildColumnDefaults, Extent, outlineAttr, renderRow, rowOpenTag, } from './row-xml.js';
 import { planSharedFormulas } from './shared-formulas.js';
 import { autoFilterXml, headerFooterXml, pageBreaksXml, pageMarginsXml, pageSetupXml, printOptionsXml, sheetProtectionXml, sheetPrXml, sheetViewsXml, } from './sheet-properties.js';
 import { x14Ext } from './x14-ext.js';
-export class Extent {
-    top = Infinity;
-    left = Infinity;
-    bottom = -Infinity;
-    right = -Infinity;
-    constructor(seed) {
-        if (seed) {
-            this.top = seed.top;
-            this.left = seed.left;
-            this.bottom = seed.bottom;
-            this.right = seed.right;
-        }
-    }
-    get isEmpty() {
-        return this.bottom === -Infinity;
-    }
-    add(row, minCol, maxCol) {
-        if (minCol === Infinity)
-            return;
-        if (row < this.top)
-            this.top = row;
-        if (row > this.bottom)
-            this.bottom = row;
-        if (minCol < this.left)
-            this.left = minCol;
-        if (maxCol > this.right)
-            this.right = maxCol;
-    }
-}
-export function worksheetXml(sheet, tables, styles, references, hyperlinks, sharedStrings, active, flushed) {
+export function worksheetXml(inputs) {
+    const { sheet, tables, styles, references, hyperlinks, sharedStrings, dateEpoch, active, flushed } = inputs;
     validateMerges(sheet);
     const columnDefaults = buildColumnDefaults(sheet);
     const sharedRoles = planSharedFormulas(sheet);
-    const rowOutline = scanRowOutline(sheet);
+    const extLinks = dataBarExtLinks(sheet.conditionalFormattings);
+    const rowOutline = scanRowOutline(sheet, flushed);
     const collapsedSummaries = rowOutline.collapsedSummaries;
     const context = {
         columnDefaults,
@@ -59,6 +27,7 @@ export function worksheetXml(sheet, tables, styles, references, hyperlinks, shar
         sharedStrings,
         sharedRoles,
         collapsedSummaries,
+        dateEpoch,
     };
     const liveRows = [];
     const extent = new Extent(flushed?.extent);
@@ -69,11 +38,9 @@ export function worksheetXml(sheet, tables, styles, references, hyperlinks, shar
         liveRows.push({ number: entry.number, xml });
         extent.add(entry.number, minCol, maxCol);
     }
-    const dimensionRef = extent.isEmpty
-        ? 'A1'
-        : `${encodeAddress(extent.left, extent.top)}:${encodeAddress(extent.right, extent.bottom)}`;
+    const dimensionRef = extent.isEmpty ? 'A1' : encodeRect(extent);
     const orderedRows = flushed
-        ? [...flushed.rows, ...liveRows].sort((a, b) => a.number - b.number)
+        ? [...flushed.rows.map((row) => completeCollapsed(row, collapsedSummaries)), ...liveRows].sort((a, b) => a.number - b.number)
         : liveRows;
     const bodyXml = orderedRows.map((row) => row.xml).join('');
     const sheetData = bodyXml === '' ? '<sheetData/>' : `<sheetData>${bodyXml}</sheetData>`;
@@ -84,14 +51,14 @@ export function worksheetXml(sheet, tables, styles, references, hyperlinks, shar
         sheetViewsXml(sheet.view, active) +
         sheetFormatPr(sheet.properties, {
             col: maxColumnOutlineLevel(sheet),
-            row: Math.max(rowOutline.maxLevel, flushed?.maxRowOutlineLevel ?? 0),
+            row: rowOutline.maxLevel,
         }) +
         colsXml(sheet, styles) +
         sheetData +
         sheetProtectionXml(sheet.protection) +
         autoFilterXml(sheet.autoFilter) +
         mergeCellsXml(sheet.merges) +
-        conditionalFormattingsXml(sheet.conditionalFormattings, styles) +
+        conditionalFormattingsXml(sheet.conditionalFormattings, styles, extLinks) +
         dataValidationsXml(sheet.dataValidations) +
         hyperlinksXml(hyperlinks) +
         printOptionsXml(sheet.printOptions) +
@@ -105,57 +72,12 @@ export function worksheetXml(sheet, tables, styles, references, hyperlinks, shar
         refElement('legacyDrawingHF', references.legacyDrawingHFRelId) +
         refElement('picture', references.backgroundRelId) +
         tablePartsXml(tables) +
-        worksheetExtLstXml(sheet, references.slicerRelIds) +
+        worksheetExtLstXml(sheet, references.slicerRelIds, extLinks) +
         '</worksheet>');
 }
-export function buildColumnDefaults(sheet) {
-    const columnDefaults = new Map();
-    for (const { index, properties } of sheet.columns())
-        columnDefaults.set(index, properties ?? {});
-    return columnDefaults;
-}
-export function renderRow(entry, ctx) {
-    const { number, cells, properties } = entry;
-    const rendered = cells.filter((cell) => cell.value !== null || cellHasOwnStyle(cell));
-    const attrs = rowAttrs(properties, ctx.styles, ctx.collapsedSummaries.has(number));
-    if (rendered.length === 0 && attrs === '')
-        return { xml: '', minCol: Infinity, maxCol: -Infinity };
-    const rowFill = properties?.fill;
-    const cellsXml = rendered
-        .map((cell) => {
-        const style = ctx.styles.styleId(composeCellStyle(cell, rowFill, ctx.columnDefaults.get(cell.col)));
-        return cellXml(cell, style, ctx.sharedRoles.get(cell.address), ctx.sharedStrings);
-    })
-        .join('');
-    let minCol = Infinity;
-    let maxCol = -Infinity;
-    for (const cell of rendered) {
-        if (cell.col < minCol)
-            minCol = cell.col;
-        if (cell.col > maxCol)
-            maxCol = cell.col;
-    }
-    return { xml: `<row r="${number}"${attrs}>${cellsXml}</row>`, minCol, maxCol };
-}
-function composeCellStyle(cell, rowFill, colDef) {
-    const style = {};
-    for (const facet of CELL_STYLE_FACETS)
-        inheritFacet(style, facet, cell, colDef);
-    style.fill = cell.fill ?? rowFill ?? colDef?.fill;
-    style.numFmt = cell.numFmt ?? colDef?.numFmt ?? dateDefaultNumFmt(cell.value);
-    if (cell.quotePrefix !== undefined)
-        style.quotePrefix = cell.quotePrefix;
-    const xfId = cell[NAMED_STYLE_ID];
-    if (xfId !== undefined)
-        style.xfId = xfId;
-    return style;
-}
-function inheritFacet(target, key, cell, colDef) {
-    target[key] = cell[key] ?? colDef?.[key];
-}
-function worksheetExtLstXml(sheet, slicerRelIds) {
+function worksheetExtLstXml(sheet, slicerRelIds, extLinks) {
     const exts = [
-        conditionalFormattingsExtXml(sheet.conditionalFormattings),
+        conditionalFormattingsExtXml(sheet.conditionalFormattings, extLinks),
         dataValidationsExtXml(sheet.dataValidations),
         slicerListExtXml(slicerRelIds),
     ].filter((ext) => ext !== '');
@@ -181,7 +103,7 @@ function validateMerges(sheet) {
                 top <= region.bottom &&
                 bottom >= region.top;
             if (overlaps) {
-                throw new AuthoringError(`merged range ${merge} overlaps table "${table.name}" (${table.range}): Excel forbids a merge inside a table`);
+                throw new AuthoringError(`merged range ${merge} overlaps table ${quoted(table.name)} (${table.range}): Excel forbids a merge inside a table`);
             }
         }
     }
@@ -203,7 +125,8 @@ function tablePartsXml(tables) {
     const parts = tables.map(({ relId }) => `<tablePart r:id="${relId}"/>`).join('');
     return `<tableParts count="${tables.length}">${parts}</tableParts>`;
 }
-export function worksheetRelsXml(tables, drawing, comments, threadedComments, printerSettings, background, hyperlinks, preservedReferences, pivots) {
+export function worksheetRelsXml(plan) {
+    const { tables, drawing, comments, threadedComments, printerSettings, background, hyperlinks, preservedRefs: preservedReferences, pivots, } = plan;
     const rels = [
         ...tables.map(({ relId, number }) => relationship(relId, REL.table, targetFromWorksheet(tablePart(number)))),
         ...pivots.map((pivot) => relationship(pivot.sheetRelId, REL.pivotTable, targetFromWorksheet(pivotTablePart(pivot.number)))),
@@ -233,12 +156,10 @@ export function worksheetRelsXml(tables, drawing, comments, threadedComments, pr
             : [
                 relationship(background.relId, REL.image, targetFromWorksheet(mediaPart(background.mediaNumber, background.extension))),
             ]),
-        ...preservedReferences.map((reference) => relationship(reference.relId, reference.relType, escapeAttr(targetFromWorksheet(reference.entryPath)))),
+        ...preservedReferences.map((reference) => relationship(reference.relId, reference.relType, targetFromWorksheet(reference.entryPath))),
         ...hyperlinks
-            .filter((link) => link.relId !== undefined && link.target !== undefined)
-            .map((link) => relationship(link.relId, REL.hyperlink, link.target, {
-            external: true,
-        })),
+            .filter(isExternalHyperlink)
+            .map((link) => relationship(link.relId, REL.hyperlink, link.target, { external: true })),
     ];
     return relationshipsPart(rels);
 }
@@ -255,12 +176,6 @@ function sheetFormatPr(properties, outlineLevel) {
     attrs += outlineAttr('outlineLevelRow', outlineLevel.row);
     return `<sheetFormatPr${attrs}/>`;
 }
-function outlineAttr(name, level) {
-    if (level === undefined)
-        return '';
-    const text = numberText(level);
-    return level > 0 ? ` ${name}="${text}"` : '';
-}
 function maxColumnOutlineLevel(sheet) {
     let max = 0;
     for (const column of sheet.columns())
@@ -313,33 +228,35 @@ function colBody(properties, styles) {
     }
     return meaningful ? attrs : null;
 }
-function rowAttrs(properties, styles, collapsedSummary) {
-    if (properties === undefined)
-        return collapsedSummary ? ' collapsed="1"' : '';
-    let attrs = '';
-    if (properties.height !== undefined)
-        attrs += ` ht="${numberText(properties.height)}" customHeight="1"`;
-    if (properties.hidden)
-        attrs += ' hidden="1"';
-    attrs += outlineAttr('outlineLevel', properties.outlineLevel);
-    if (properties.collapsed || collapsedSummary)
-        attrs += ' collapsed="1"';
-    const style = styles.styleId({ fill: properties.fill });
-    if (style !== 0)
-        attrs += ` s="${style}" customFormat="1"`;
-    return attrs;
+function completeCollapsed(row, collapsedSummaries) {
+    if (!collapsedSummaries.has(row.number) || row.attrs.includes(' collapsed="1"')) {
+        return { number: row.number, xml: row.xml };
+    }
+    const open = rowOpenTag(row.number);
+    if (!row.xml.startsWith(open)) {
+        throw new InternalError(`flushed row ${row.number} does not open with ${quoted(open)}`);
+    }
+    return {
+        number: row.number,
+        xml: `${open} collapsed="1"${row.xml.slice(open.length)}`,
+    };
 }
-function scanRowOutline(sheet) {
+function scanRowOutline(sheet, flushed) {
     const level = new Map();
     const hidden = new Map();
     let maxLevel = 0;
-    for (const { number, properties } of sheet.rows()) {
-        const rowLevel = properties?.outlineLevel ?? 0;
-        assertWritableNumber(rowLevel);
+    const note = (number, rowLevel, rowHidden) => {
+        assertWritableLevel(`row ${number} outlineLevel`, rowLevel);
         level.set(number, rowLevel);
-        hidden.set(number, properties?.hidden ?? false);
+        hidden.set(number, rowHidden);
         if (rowLevel > maxLevel)
             maxLevel = rowLevel;
+    };
+    for (const [number, entry] of flushed?.rowOutline ?? []) {
+        note(number, entry.outlineLevel, entry.hidden);
+    }
+    for (const { number, properties } of sheet.rows()) {
+        note(number, properties?.outlineLevel ?? 0, properties?.hidden ?? false);
     }
     const levelOf = (row) => level.get(row) ?? 0;
     const step = sheet.outline.summaryBelow === false ? 1 : -1;
@@ -348,7 +265,7 @@ function scanRowOutline(sheet) {
         let detail = summary + step;
         let sawDetail = false;
         let allHidden = true;
-        while (levelOf(detail) > summaryLevel) {
+        while (level.get(detail) !== undefined && levelOf(detail) > summaryLevel) {
             sawDetail = true;
             if (!hidden.get(detail))
                 allHidden = false;
@@ -359,101 +276,3 @@ function scanRowOutline(sheet) {
     }
     return { collapsedSummaries, maxLevel };
 }
-function dateDefaultNumFmt(value) {
-    const date = value instanceof Date
-        ? value
-        : (isFormulaValue(value) || isSharedFormulaValue(value)) && value.result instanceof Date
-            ? value.result
-            : undefined;
-    return date !== undefined && !Number.isNaN(date.getTime()) ? DEFAULT_DATE_NUMFMT : undefined;
-}
-function cellXml(cell, style, shared, sharedStrings) {
-    const ref = cell.address;
-    const value = cell.value;
-    const s = style !== 0 ? ` s="${style}"` : '';
-    const formula = cellFormulaXml(ref, s, value, shared);
-    if (formula !== undefined)
-        return formula;
-    if (value instanceof Date) {
-        if (Number.isNaN(value.getTime()))
-            return `<c r="${ref}"${s}/>`;
-        return `<c r="${ref}"${s}><v>${numberText(dateToSerial(value))}</v></c>`;
-    }
-    if (typeof value === 'number') {
-        if (!Number.isFinite(value))
-            return `<c r="${ref}"${s}/>`;
-        return `<c r="${ref}"${s}><v>${numberText(value)}</v></c>`;
-    }
-    if (typeof value === 'boolean') {
-        return `<c r="${ref}"${s} t="b"><v>${value ? 1 : 0}</v></c>`;
-    }
-    if (typeof value === 'string') {
-        if (sharedStrings !== null) {
-            return `<c r="${ref}"${s} t="s"><v>${sharedStrings.intern(value)}</v></c>`;
-        }
-        return `<c r="${ref}"${s} t="inlineStr"><is>${textElement(value)}</is></c>`;
-    }
-    if (isRichTextValue(value)) {
-        if (sharedStrings !== null) {
-            return `<c r="${ref}"${s} t="s"><v>${sharedStrings.intern(value)}</v></c>`;
-        }
-        return `<c r="${ref}"${s} t="inlineStr"><is>${richTextRunsXml(value.richText)}</is></c>`;
-    }
-    if (isHyperlinkValue(value)) {
-        const label = typeof value.text === 'string'
-            ? textElement(value.text)
-            : richTextRunsXml(value.text.richText);
-        return `<c r="${ref}"${s} t="inlineStr"><is>${label}</is></c>`;
-    }
-    if (isErrorValue(value)) {
-        return `<c r="${ref}"${s} t="e"><v>${value.error}</v></c>`;
-    }
-    if (value === null)
-        return `<c r="${ref}"${s}/>`;
-    throw new InternalError(`writing a ${detectValueType(value)} cell value has no arm: every CellValue kind is handled above`);
-}
-function cellFormulaXml(ref, s, value, shared) {
-    if (shared !== undefined) {
-        if (shared.ref !== undefined && isFormulaValue(value)) {
-            const f = `<f t="shared" ref="${shared.ref}" si="${shared.si}">${escapeText(mangleFormula(value.formula))}</f>`;
-            return formulaBodyXml(ref, s, f, value.result);
-        }
-        const result = isSharedFormulaValue(value) ? value.result : undefined;
-        return formulaBodyXml(ref, s, `<f t="shared" si="${shared.si}"/>`, result);
-    }
-    if (isDataTableFormulaValue(value)) {
-        const attrs = `ref="${escapeAttr(value.ref)}"` +
-            ` dt2D="${value.dataTable2D ? 1 : 0}"` +
-            ` dtr="${value.dataTableRow ? 1 : 0}"` +
-            textAttr('r1', value.r1) +
-            textAttr('r2', value.r2);
-        return formulaBodyXml(ref, s, `<f t="dataTable" ${attrs}/>`, value.result);
-    }
-    if (isFormulaValue(value)) {
-        return formulaBodyXml(ref, s, `<f>${escapeText(mangleFormula(value.formula))}</f>`, value.result);
-    }
-    return undefined;
-}
-function formulaBodyXml(ref, s, f, result) {
-    if (result === undefined || (typeof result === 'number' && !Number.isFinite(result))) {
-        return `<c r="${ref}"${s}>${f}</c>`;
-    }
-    if (typeof result === 'number') {
-        return `<c r="${ref}"${s}>${f}<v>${numberText(result)}</v></c>`;
-    }
-    if (typeof result === 'boolean') {
-        return `<c r="${ref}"${s} t="b">${f}<v>${result ? 1 : 0}</v></c>`;
-    }
-    if (typeof result === 'string') {
-        return `<c r="${ref}"${s} t="str">${f}<v>${escapeSpreadsheetText(result)}</v></c>`;
-    }
-    if (isErrorValue(result)) {
-        return `<c r="${ref}"${s} t="e">${f}<v>${result.error}</v></c>`;
-    }
-    if (result instanceof Date) {
-        if (Number.isNaN(result.getTime()))
-            return `<c r="${ref}"${s}>${f}</c>`;
-        return `<c r="${ref}"${s}>${f}<v>${numberText(dateToSerial(result))}</v></c>`;
-    }
-    throw new InternalError('writing a non-primitive formula result has no arm: every FormulaResult kind is handled above');
-}

package/dist/io/xlsx/write-stream.d.ts

@@ -3,13 +3,15 @@ import type { AutoFilter } from '../../core/autofilter.ts';
 import type { Cell } from '../../core/cell.ts';
 import type { ConditionalFormatting } from '../../core/conditional-formatting.ts';
 import type { DataValidation } from '../../core/data-validation.ts';
+import type { DateEpoch } from '../../core/date.ts';
 import type { AnchorPoint } from '../../core/image.ts';
+import { INTERNAL } from '../../core/internal.ts';
 import type { SheetProtectionOptions } from '../../core/protection.ts';
 import { type CellValue } from '../../core/value.ts';
 import { type AddImageOptions, type AddWorksheetOptions, Workbook } from '../../core/workbook.ts';
 import type { Worksheet } from '../../core/worksheet.ts';
+import { type FlushedSheet } from './row-xml.ts';
 import type { StyleRegistry } from './styles.ts';
-import { type FlushedSheet } from './write.ts';
 /** Calculation settings applied to the streamed workbook. Mirrors the {@link Workbook} flags. */
 export interface CalcProperties {
     /** Ask the consumer to recalculate every formula on open: the OOXML `fullCalcOnLoad` flag. */
@@ -45,6 +47,13 @@ export type WorkbookStreamWriterOptions = SinkOptions & {
      * same {@link WriteOptions.useSharedStrings} the buffered writer exposes. Off by default.
      */
     readonly useSharedStrings?: boolean;
+    /**
+     * Which date system this workbook's serials count in ({@link Workbook.dateEpoch}). A construction
+     * option rather than a settable property, unlike on the buffered writer: an eager writer serialises
+     * each row as it is committed, so a system changed part-way through would leave the rows before the
+     * change counting from a different day than the rows after it.
+     */
+    readonly dateEpoch?: DateEpoch;
 };
 /**
  * A row appended to a {@link WorksheetStreamWriter}. Style its cells through {@link cells}, then call
@@ -68,7 +77,13 @@ export declare class StreamedRow {
  */
 export declare class WorksheetStreamWriter {
     #private;
-    constructor(sheet: Worksheet, eager: boolean, styles: StyleRegistry);
+    private constructor();
+    /**
+     * The workbook writer's construction channel. A static member keyed by the same symbol as the
+     * instance one below, so both halves of this class's internal wiring are reached the one way; see
+     * `core/internal.ts`.
+     */
+    static readonly [INTERNAL]: WorksheetStreamWriterFactory;
     /** The sheet's name. */
     get name(): string;
     /** The number of rows written so far. Spans gaps and formatted-only rows, like the model, and
@@ -78,16 +93,6 @@ export declare class WorksheetStreamWriter {
     addRow(values: CellValue[]): StreamedRow;
     /** Append a batch of rows in one call, each landing directly below the previous. */
     addRows(rows: CellValue[][]): StreamedRow[];
-    /**
-     * Serialise an eagerly-committed row and release its cells from the model. Called by
-     * {@link StreamedRow.commit}; the row's `<row>` XML is retained (interned into the workbook's live
-     * style registry so its ids stay valid) and the cell graph is dropped, bounding peak memory.
-     *
-     * @throws {AuthoringError} if the row carries a shared-formula cell: a finished row cannot join the
-     *   whole-sheet formula planning, so shared formulas must be authored through {@link getCell}.
-     */
-    flushRow(number: number, cells: readonly Cell[]): void;
-    flushedSheet(): FlushedSheet | undefined;
     /**
      * Address a cell by its A1 reference to read or style it before the sheet is committed. The row it
      * names must still be live: a row whose {@link StreamedRow.commit} has run is finished.
@@ -139,6 +144,41 @@ export declare class WorksheetStreamWriter {
     /** Whether the sheet has been committed. */
     get committed(): boolean;
     get model(): Worksheet;
+    readonly [INTERNAL]: WorksheetStreamWriterInternals;
+}
+/**
+ * How a {@link WorksheetStreamWriter} comes into being. Its parameters are the writer's own plumbing
+ * -- the interning table its rows' style ids are assigned from, the epoch its dates are serialised
+ * against -- and a consumer supplies neither, because a consumer receives the sheet writer from
+ * {@link WorkbookStreamWriter.addWorksheet}. Reached as `WorksheetStreamWriter[INTERNAL]`.
+ */
+export interface WorksheetStreamWriterFactory {
+    create(sheet: Worksheet, eager: boolean, styles: StyleRegistry, dateEpoch: DateEpoch): WorksheetStreamWriter;
+}
+/**
+ * What the streaming writer's own machinery may do to a sheet writer that a caller may not, the same
+ * boundary `sheet[INTERNAL]` draws around the model. Reached as `writer[INTERNAL]`; see
+ * `core/internal.ts`.
+ *
+ * Both members were public until they were not. Neither is callable by anyone but this module, and
+ * between them they named seven writer-internal types -- `StyleRegistry`, `FlushedSheet` and the
+ * shapes those reach -- on a published class's signature, so a consumer could hold values whose types
+ * the package would not export. They carried `@unpublished` to record that, which is a note rather
+ * than a boundary; this is the boundary.
+ */
+export interface WorksheetStreamWriterInternals {
+    /**
+     * Serialise an eagerly-committed row and release its cells from the model. Called by
+     * {@link StreamedRow.commit}; the row's `<row>` XML is retained (interned into the workbook's live
+     * style registry so its ids stay valid) and the cell graph is dropped, bounding peak memory.
+     *
+     * @throws {AuthoringError} if the row carries a shared-formula cell: a finished row cannot join the
+     *   whole-sheet formula planning, so shared formulas must be authored through
+     *   {@link WorksheetStreamWriter.getCell}.
+     */
+    flushRow(number: number, cells: readonly Cell[]): void;
+    /** The rows this writer flushed, or undefined if none. Handed to `buildPackageParts` at commit. */
+    flushedSheet(): FlushedSheet | undefined;
 }
 /**
  * A workbook written incrementally to a Node stream. Add worksheets, append their rows, commit each
@@ -169,9 +209,18 @@ export declare class WorkbookStreamWriter {
     /** Create a worksheet and append it to the workbook. */
     addWorksheet(name: string, options?: AddWorksheetOptions): WorksheetStreamWriter;
     /**
-     * Assemble the workbook into its package, stream the bytes through {@link stream}, and resolve with
-     * the same bytes. Every sheet is frozen first, so a row added after this rejects legibly. Idempotent
-     * only in that a second call throws rather than re-emitting.
+     * Assemble the workbook into its package and stream the bytes out. Every sheet is frozen first, so
+     * a row added after this rejects legibly. Idempotent only in that a second call throws rather than
+     * re-emitting.
+     *
+     * **What it resolves with, and why it can be `undefined`.** The archive is handed back only when
+     * somebody asked for it: when no sink was supplied, or when {@link stream} was touched, since a
+     * `PassThrough` nobody drained would otherwise be the only copy. A caller who passed `{filename}`
+     * or their own `stream` and never reached for {@link stream} gets `undefined`, and the package is
+     * never materialised as a whole: retaining every chunk to concatenate them at the end costs a
+     * second full-size buffer on top of the part map and the archive itself, which is exactly the
+     * memory the caller passed a sink to avoid. The type says so rather than the prose alone, because
+     * a promise that resolves with a value the caller was told to ignore is a promise they will use.
      *
      * If assembling or zipping the package fails, the returned promise rejects *and* every stream this
      * writer was given or handed out is destroyed with that error. A caller piping {@link stream}, or
@@ -179,6 +228,6 @@ export declare class WorkbookStreamWriter {
      * end; and it is an `error` rather than a clean `end` because the bytes written so far are a
      * truncated package that must not be read as a whole one.
      */
-    commit(): Promise<Uint8Array>;
+    commit(): Promise<Uint8Array | undefined>;
 }
 export {};