@shbernal/ts-xlsx 1.0.0

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

@@ -0,0 +1,171 @@
+import { type Readable, type Writable } from 'node:stream';
+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 { AnchorPoint } from '../../core/image.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 { 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. */
+    fullCalcOnLoad?: boolean;
+}
+type SinkOptions = {
+    /**
+     * Write the package to a caller-owned {@link Writable} sink — an outbound upload, a cloud-SDK
+     * stream, any destination the caller controls. {@link WorkbookStreamWriter.commit} pushes every
+     * chunk into it and settles only once the sink has finished (or rejects if it errors), so a
+     * caller can deterministically sequence work after the upload completes. Mutually exclusive
+     * with {@link filename}.
+     */
+    readonly stream: Writable;
+    readonly filename?: never;
+} | {
+    readonly stream?: never;
+    /**
+     * Write the package to a file at this path. The writer opens a `fs.createWriteStream` for it; if
+     * the destination cannot be opened (bad path, name too long) the stream errors and
+     * {@link WorkbookStreamWriter.commit} rejects with that I/O error rather than hanging. Mutually
+     * exclusive with {@link stream}.
+     */
+    readonly filename: string;
+} | {
+    readonly stream?: never;
+    readonly filename?: never;
+};
+/** Options fixed at construction that shape the whole streamed package. */
+export type WorkbookStreamWriterOptions = SinkOptions & {
+    /**
+     * Pool plain string cell values into a shared-strings table rather than storing each inline — the
+     * same {@link WriteOptions.useSharedStrings} the buffered writer exposes. Off by default.
+     */
+    readonly useSharedStrings?: boolean;
+};
+/**
+ * A row appended to a {@link WorksheetStreamWriter}. Style its cells through {@link cells}, then call
+ * {@link commit} to mark it finished. In an eager (inline-strings) writer, committing serialises the
+ * row and frees its cells from the model, bounding peak memory; with `useSharedStrings` on it is a
+ * no-op and the row stays live until the workbook commits.
+ */
+export declare class StreamedRow {
+    #private;
+    constructor(cells: readonly Cell[], sheet: WorksheetStreamWriter | null, number: number);
+    /** The cells this row materialised, for styling before it is committed. */
+    get cells(): readonly Cell[];
+    /** Finalise the row: an eager writer serialises it now and releases its cells; otherwise a no-op.
+     * Committing twice is harmless — the second call does nothing rather than re-emitting the row. */
+    commit(): void;
+}
+/**
+ * A worksheet being written incrementally. Append rows with {@link addRow}/{@link addRows}, style
+ * cells through {@link getCell}, then {@link commit} to freeze it — after which any further mutation
+ * is rejected with a legible error rather than silently accepted or crashing.
+ */
+export declare class WorksheetStreamWriter {
+    #private;
+    constructor(sheet: Worksheet, eager: boolean, styles: StyleRegistry);
+    /** The sheet's name. */
+    get name(): string;
+    /** The number of rows written so far — spans gaps and formatted-only rows, like the model, and
+     * survives the eviction of eagerly-flushed rows. */
+    get rowCount(): number;
+    /** Append one row of values after the last used row; the cells are returned for styling. */
+    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 {@link 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. */
+    getCell(reference: string): Cell;
+    /**
+     * Attach a data validation to a range before the sheet is committed. Delegates to the model, so the
+     * streamed package emits the `<dataValidations>` block in its CT_Worksheet position — before
+     * `<hyperlinks>` — because both writers share one worksheet serializer.
+     */
+    addDataValidation(sqref: string, rule: DataValidation, options?: {
+        extended?: boolean;
+    }): void;
+    /**
+     * Attach a conditional formatting to a range before the sheet is committed. Like every other block,
+     * it lands in its schema-mandated slot — after `<mergeCells>`, before `<dataValidations>` and
+     * `<hyperlinks>` — since the streamed sheet is serialized through the same path as a buffered write.
+     */
+    addConditionalFormatting(formatting: ConditionalFormatting): void;
+    /**
+     * Anchor a workbook image (the id from {@link WorkbookStreamWriter.addImage}) to this sheet,
+     * spanning the rectangle from the top-left grid point `tl` to the bottom-right `br`. The streamed
+     * package emits the drawing part, its media relationship, and the sheet's `<drawing>` reference
+     * exactly as a buffered write does — both writers share `buildPackageParts`.
+     */
+    addImage(imageId: number, anchor: {
+        readonly tl: AnchorPoint;
+        readonly br: AnchorPoint;
+    }): void;
+    /**
+     * Apply the sheet's autofilter before it is committed; mirrors {@link Worksheet.autoFilter}. The
+     * streamed package emits `<autoFilter>` in its CT_Worksheet slot — after `<sheetProtection>` — and
+     * contributes the hidden `_FilterDatabase` defined name, exactly as a buffered write does.
+     */
+    set autoFilter(filter: string | AutoFilter | undefined);
+    get autoFilter(): AutoFilter | undefined;
+    /**
+     * Apply sheet-level protection before the sheet is committed; mirrors {@link Worksheet.protect}. The
+     * shared serializer places `<sheetProtection>` ahead of `<autoFilter>` per CT_Worksheet, so a
+     * streamed sheet carrying both stays valid rather than corrupt.
+     */
+    protect(password?: string, options?: SheetProtectionOptions): void;
+    /** Freeze the sheet: no more rows or edits may be added after this. */
+    commit(): void;
+    /** Whether the sheet has been committed. */
+    get committed(): boolean;
+    get model(): Worksheet;
+}
+/**
+ * A workbook written incrementally to a Node stream. Add worksheets, append their rows, commit each
+ * sheet, then {@link commit} the workbook to assemble and stream the package. The produced bytes are
+ * available both as the resolved value of `commit()` and through {@link stream} (a Node `Readable`
+ * that a caller can `pipe`).
+ */
+export declare class WorkbookStreamWriter {
+    #private;
+    /** Calculation settings for the workbook; set `fullCalcOnLoad` before committing to emit it. */
+    readonly calcProperties: CalcProperties;
+    constructor(options?: WorkbookStreamWriterOptions);
+    /** Document-level metadata written to the package's core properties. */
+    get properties(): Workbook['properties'];
+    /**
+     * The output stream carrying the package bytes. A caller drives it with Node's standard idiom —
+     * `writer.stream.pipe(out)` — which composes because `pipe` returns its destination. The stream is
+     * created lazily on first access so a caller handing the writer its own sink is still free to
+     * ignore this one.
+     */
+    get stream(): Readable;
+    /**
+     * Register a picture's bytes on the workbook's shared media registry and return its id, to anchor
+     * on any sheet with {@link WorksheetStreamWriter.addImage}. Mirrors {@link Workbook.addImage}: one
+     * media part backs an image anchored on several sheets. Rejected once the workbook is committed.
+     */
+    addImage(options: AddImageOptions): number;
+    /** 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.
+     */
+    commit(): Promise<Uint8Array>;
+}
+export {};

package/dist/io/xlsx/write-stream.js

@@ -0,0 +1,399 @@
+// The streaming `.xlsx` writer: author a workbook incrementally and emit its package through a Node
+// stream, rather than holding the finished bytes in one buffer as {@link writeXlsx} does.
+//
+// A producer adds worksheets, appends rows as it generates them, commits each sheet, then commits the
+// workbook — at which point the package is assembled and streamed out. The output goes to whichever
+// destination the caller chose at construction: its own pull-based `stream` to pipe, a caller-owned
+// `Writable` sink (an outbound upload), or a `filename` the writer opens. In every case `commit()`
+// settles — it resolves once a supplied sink has flushed the whole package and rejects if that sink
+// errors (an unopenable file), never hanging on a finish signal that will not come. The output rides a
+// genuinely
+// streamed zip container (fflate's `Zip`/`ZipDeflate`), which computes each entry's CRC-32
+// incrementally, so the archive is well-formed by construction — the defect the upstream "streaming
+// writer emits a corrupt zip" reports describe is structurally absent here. The bytes reload
+// identically to a whole-file write because both writers share `buildPackageParts` for every part.
+//
+// Peak memory: a row committed with `row.commit()` is serialised to its `<row>` XML immediately and
+// its cells evicted from the model, so an append-driven producer holds only the rows still in flight
+// rather than the whole sheet's cell graph. The eagerly-rendered rows intern into the workbook's live
+// style registry — the same one that emits `xl/styles.xml` — so their style ids stay correct; their
+// XML is handed to `buildPackageParts` and emitted at the head of `<sheetData>`. This eager path runs
+// with strings inline (a shared-strings pool is inherently whole-workbook, so it defeats bounding);
+// turning `useSharedStrings` on falls back to holding every row live until commit. A flushed row is a
+// finished row: it cannot join whole-sheet derivations, so a shared-formula clone in a committed row
+// is rejected, and rows reached only through `getCell` (never `row.commit()`) stay live and serialise
+// the ordinary way. The package bytes themselves are still assembled once at commit — a later slice
+// can flush each sheet's `<sheetData>` straight into its streamed zip entry to bound that half too.
+import { createWriteStream } from 'node:fs';
+import { PassThrough } from 'node:stream';
+import { Zip, ZipDeflate } from 'fflate';
+import { encodeAddress } from "../../core/address.js";
+import { INTERNAL } from "../../core/internal.js";
+import { isSharedFormulaValue } from "../../core/value.js";
+import { Workbook } from "../../core/workbook.js";
+import { AuthoringError } from "../../errors.js";
+import { buildColumnDefaults, buildPackageParts, createStyleRegistry, Extent, renderRow, } from "./write.js";
+/**
+ * A row appended to a {@link WorksheetStreamWriter}. Style its cells through {@link cells}, then call
+ * {@link commit} to mark it finished. In an eager (inline-strings) writer, committing serialises the
+ * row and frees its cells from the model, bounding peak memory; with `useSharedStrings` on it is a
+ * no-op and the row stays live until the workbook commits.
+ */
+export class StreamedRow {
+    #cells;
+    #sheet;
+    #number;
+    #committed = false;
+    constructor(cells, sheet, number) {
+        this.#cells = cells;
+        this.#sheet = sheet;
+        this.#number = number;
+    }
+    /** The cells this row materialised, for styling before it is committed. */
+    get cells() {
+        return this.#cells;
+    }
+    /** Finalise the row: an eager writer serialises it now and releases its cells; otherwise a no-op.
+     * Committing twice is harmless — the second call does nothing rather than re-emitting the row. */
+    commit() {
+        if (this.#committed)
+            return;
+        this.#committed = true;
+        this.#sheet?.flushRow(this.#number, this.#cells);
+    }
+}
+/**
+ * A worksheet being written incrementally. Append rows with {@link addRow}/{@link addRows}, style
+ * cells through {@link getCell}, then {@link commit} to freeze it — after which any further mutation
+ * is rejected with a legible error rather than silently accepted or crashing.
+ */
+export class WorksheetStreamWriter {
+    #sheet;
+    #eager;
+    #styles;
+    #committed = false;
+    // The last row number this writer appended, tracked independently of the model: an eager writer
+    // evicts flushed rows, which lowers the model's used range, so leaning on it would reuse numbers.
+    #lastRow = 0;
+    // The column defaults an eagerly-rendered row inherits, frozen at the first flush so every flushed
+    // row composes against the same columns even as later ones are defined.
+    #columnDefaults;
+    #flushedRows = [];
+    #extent = new Extent();
+    #maxRowOutlineLevel = 0;
+    constructor(sheet, eager, styles) {
+        this.#sheet = sheet;
+        this.#eager = eager;
+        this.#styles = styles;
+    }
+    /** The sheet's name. */
+    get name() {
+        return this.#sheet.name;
+    }
+    /** The number of rows written so far — spans gaps and formatted-only rows, like the model, and
+     * survives the eviction of eagerly-flushed rows. */
+    get rowCount() {
+        return Math.max(this.#lastRow, this.#sheet.rowCount);
+    }
+    /** Append one row of values after the last used row; the cells are returned for styling. */
+    addRow(values) {
+        this.#assertOpen();
+        if (!this.#eager)
+            return new StreamedRow(this.#sheet.addRow(values), null, 0);
+        const number = this.#nextRowNumber();
+        return new StreamedRow(this.#placeRow(number, values), this, number);
+    }
+    /** Append a batch of rows in one call, each landing directly below the previous. */
+    addRows(rows) {
+        this.#assertOpen();
+        if (!this.#eager)
+            return this.#sheet.addRows(rows).map((cells) => new StreamedRow(cells, null, 0));
+        return rows.map((values) => this.addRow(values));
+    }
+    // The next append position: past both this writer's own high-water mark and any rows a `getCell`
+    // materialised, so appends never collide with random-access edits or with already-evicted rows.
+    #nextRowNumber() {
+        this.#lastRow = Math.max(this.#lastRow, this.#sheet.rowCount) + 1;
+        return this.#lastRow;
+    }
+    // Materialise a positional row at an explicit number (the model's own append would reuse numbers once
+    // eviction shrinks its used range), returning the cells for styling. A hole leaves its cell absent.
+    #placeRow(number, values) {
+        const cells = [];
+        values.forEach((value, index) => {
+            const cell = this.#sheet.getCell(encodeAddress(index + 1, number));
+            cell.value = value;
+            cells.push(cell);
+        });
+        return cells;
+    }
+    /**
+     * 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 {@link 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, cells) {
+        for (const cell of cells) {
+            if (isSharedFormulaValue(cell.value)) {
+                throw new AuthoringError(`row ${number} of streamed sheet "${this.#sheet.name}" carries a shared-formula cell; a ` +
+                    'committed row is finalised before the sheet is planned, so author shared formulas through ' +
+                    'getCell (leaving the row uncommitted) instead');
+            }
+        }
+        this.#columnDefaults ??= buildColumnDefaults(this.#sheet);
+        const properties = this.#sheet.getRow(number).properties;
+        // The row's outline depth is read off here because eviction is about to take its properties with
+        // it, and `<sheetFormatPr outlineLevelRow>` — written long after, once every row is flushed —
+        // reports the deepest level on the whole sheet.
+        this.#maxRowOutlineLevel = Math.max(this.#maxRowOutlineLevel, properties?.outlineLevel ?? 0);
+        const { xml, minCol, maxCol } = renderRow({ number, cells, properties }, {
+            columnDefaults: this.#columnDefaults,
+            styles: this.#styles,
+            sharedStrings: null,
+            sharedRoles: new Map(),
+            collapsedSummaries: new Set(),
+        });
+        if (xml !== '') {
+            this.#flushedRows.push({ number, xml });
+            this.#extent.add(number, minCol, maxCol);
+        }
+        this.#sheet[INTERNAL].evictRow(number);
+    }
+    // The rows this writer flushed, or undefined if none — handed to buildPackageParts at commit.
+    flushedSheet() {
+        if (this.#flushedRows.length === 0)
+            return undefined;
+        return {
+            rows: this.#flushedRows,
+            extent: this.#extent,
+            maxRowOutlineLevel: this.#maxRowOutlineLevel,
+        };
+    }
+    /** Address a cell by its A1 reference to read or style it before the sheet is committed. */
+    getCell(reference) {
+        this.#assertOpen();
+        return this.#sheet.getCell(reference);
+    }
+    /**
+     * Attach a data validation to a range before the sheet is committed. Delegates to the model, so the
+     * streamed package emits the `<dataValidations>` block in its CT_Worksheet position — before
+     * `<hyperlinks>` — because both writers share one worksheet serializer.
+     */
+    addDataValidation(sqref, rule, options = {}) {
+        this.#assertOpen();
+        this.#sheet.addDataValidation(sqref, rule, options);
+    }
+    /**
+     * Attach a conditional formatting to a range before the sheet is committed. Like every other block,
+     * it lands in its schema-mandated slot — after `<mergeCells>`, before `<dataValidations>` and
+     * `<hyperlinks>` — since the streamed sheet is serialized through the same path as a buffered write.
+     */
+    addConditionalFormatting(formatting) {
+        this.#assertOpen();
+        this.#sheet.addConditionalFormatting(formatting);
+    }
+    /**
+     * Anchor a workbook image (the id from {@link WorkbookStreamWriter.addImage}) to this sheet,
+     * spanning the rectangle from the top-left grid point `tl` to the bottom-right `br`. The streamed
+     * package emits the drawing part, its media relationship, and the sheet's `<drawing>` reference
+     * exactly as a buffered write does — both writers share `buildPackageParts`.
+     */
+    addImage(imageId, anchor) {
+        this.#assertOpen();
+        this.#sheet.addImage(imageId, anchor);
+    }
+    /**
+     * Apply the sheet's autofilter before it is committed; mirrors {@link Worksheet.autoFilter}. The
+     * streamed package emits `<autoFilter>` in its CT_Worksheet slot — after `<sheetProtection>` — and
+     * contributes the hidden `_FilterDatabase` defined name, exactly as a buffered write does.
+     */
+    set autoFilter(filter) {
+        this.#assertOpen();
+        this.#sheet.autoFilter = filter;
+    }
+    get autoFilter() {
+        return this.#sheet.autoFilter;
+    }
+    /**
+     * Apply sheet-level protection before the sheet is committed; mirrors {@link Worksheet.protect}. The
+     * shared serializer places `<sheetProtection>` ahead of `<autoFilter>` per CT_Worksheet, so a
+     * streamed sheet carrying both stays valid rather than corrupt.
+     */
+    protect(password, options = {}) {
+        this.#assertOpen();
+        this.#sheet.protect(password, options);
+    }
+    /** Freeze the sheet: no more rows or edits may be added after this. */
+    commit() {
+        this.#committed = true;
+    }
+    /** Whether the sheet has been committed. */
+    get committed() {
+        return this.#committed;
+    }
+    // Internal: the underlying model sheet, so the workbook writer can serialise it at commit time.
+    get model() {
+        return this.#sheet;
+    }
+    #assertOpen() {
+        if (this.#committed) {
+            throw new AuthoringError(`worksheet "${this.#sheet.name}" is already committed — its rows are finalised and no more can be added`);
+        }
+    }
+}
+/**
+ * A workbook written incrementally to a Node stream. Add worksheets, append their rows, commit each
+ * sheet, then {@link commit} the workbook to assemble and stream the package. The produced bytes are
+ * available both as the resolved value of `commit()` and through {@link stream} (a Node `Readable`
+ * that a caller can `pipe`).
+ */
+export class WorkbookStreamWriter {
+    #workbook = new Workbook();
+    #sheets = [];
+    #writeOptions;
+    #sink;
+    // The single style registry shared by the eager per-row flush and the commit-time serialisation, so a
+    // flushed row's style ids match the styles.xml built from the same table.
+    #styles;
+    // Eager per-row flushing runs with strings inline; a shared-strings pool is inherently whole-workbook,
+    // so it cannot bound memory — turning it on keeps every row live until commit.
+    #eager;
+    #stream;
+    #committed = false;
+    /** Calculation settings for the workbook; set `fullCalcOnLoad` before committing to emit it. */
+    calcProperties = {};
+    constructor(options = {}) {
+        this.#writeOptions = { useSharedStrings: options.useSharedStrings ?? false };
+        this.#eager = !this.#writeOptions.useSharedStrings;
+        this.#styles = createStyleRegistry(this.#workbook);
+        if (options.stream && options.filename) {
+            throw new AuthoringError('provide either a stream or a filename to the streaming writer, not both');
+        }
+        this.#sink =
+            options.stream ?? (options.filename ? createWriteStream(options.filename) : undefined);
+    }
+    /** Document-level metadata written to the package's core properties. */
+    get properties() {
+        return this.#workbook.properties;
+    }
+    /**
+     * The output stream carrying the package bytes. A caller drives it with Node's standard idiom —
+     * `writer.stream.pipe(out)` — which composes because `pipe` returns its destination. The stream is
+     * created lazily on first access so a caller handing the writer its own sink is still free to
+     * ignore this one.
+     */
+    get stream() {
+        this.#stream ??= new PassThrough();
+        return this.#stream;
+    }
+    /**
+     * Register a picture's bytes on the workbook's shared media registry and return its id, to anchor
+     * on any sheet with {@link WorksheetStreamWriter.addImage}. Mirrors {@link Workbook.addImage}: one
+     * media part backs an image anchored on several sheets. Rejected once the workbook is committed.
+     */
+    addImage(options) {
+        if (this.#committed) {
+            throw new AuthoringError('the workbook is already committed — no more images can be registered');
+        }
+        return this.#workbook.addImage(options);
+    }
+    /** Create a worksheet and append it to the workbook. */
+    addWorksheet(name, options = {}) {
+        if (this.#committed) {
+            throw new AuthoringError('the workbook is already committed — no more worksheets can be added');
+        }
+        const sheet = new WorksheetStreamWriter(this.#workbook.addWorksheet(name, options), this.#eager, this.#styles);
+        this.#sheets.push(sheet);
+        return sheet;
+    }
+    /**
+     * 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.
+     */
+    async commit() {
+        if (this.#committed) {
+            throw new AuthoringError('the workbook is already committed');
+        }
+        this.#committed = true;
+        for (const sheet of this.#sheets)
+            sheet.commit();
+        if (this.calcProperties.fullCalcOnLoad)
+            this.#workbook.fullCalcOnLoad = true;
+        // Hand every sheet's eagerly-flushed rows to the shared serialiser, which emits them alongside the
+        // rows still live in the model. The style registry is the same one the flushed rows interned into,
+        // so styles.xml stays consistent with the ids already baked into their XML.
+        const flushed = new Map();
+        for (const sheet of this.#sheets) {
+            const sheetFlushed = sheet.flushedSheet();
+            if (sheetFlushed)
+                flushed.set(sheet.model, sheetFlushed);
+        }
+        const parts = buildPackageParts(this.#workbook, {
+            ...this.#writeOptions,
+            styles: this.#styles,
+            flushed,
+        });
+        const owned = this.#stream;
+        const sink = this.#sink;
+        // Track the caller sink's terminal state before writing a byte, so an open failure that errors on a
+        // later tick (a bad filename) is caught rather than lost — the whole point of the reject-not-hang
+        // contract.
+        const sinkSettled = sink ? settleOnFinish(sink) : undefined;
+        const bytes = await streamZipPackage(parts, (chunk) => {
+            owned?.write(chunk);
+            sink?.write(chunk);
+        });
+        owned?.end();
+        sink?.end();
+        await sinkSettled;
+        return bytes;
+    }
+}
+// Resolve when a caller-supplied sink has flushed the whole package (`finish`), or reject if it errors
+// (`error`) — the commit promise must settle either way, never hang. Whichever fires first wins; the
+// other is ignored.
+function settleOnFinish(sink) {
+    return new Promise((resolve, reject) => {
+        sink.once('finish', resolve);
+        sink.once('error', reject);
+    });
+}
+// Zip the package parts through fflate's streaming container, forwarding each output chunk to `onChunk`
+// as it is produced and resolving with the whole archive once the final chunk arrives. `ZipDeflate`
+// deflates synchronously, so the callback fires inline as each part is pushed — the CRC-32 fflate
+// stamps into every entry's header therefore always matches the bytes it just compressed.
+function streamZipPackage(parts, onChunk) {
+    return new Promise((resolve, reject) => {
+        const collected = [];
+        const zip = new Zip((err, chunk, final) => {
+            if (err) {
+                reject(err);
+                return;
+            }
+            collected.push(chunk);
+            onChunk(chunk);
+            if (final)
+                resolve(concat(collected));
+        });
+        for (const [name, data] of Object.entries(parts)) {
+            const entry = new ZipDeflate(name, { level: 6 });
+            zip.add(entry);
+            entry.push(data, true);
+        }
+        zip.end();
+    });
+}
+function concat(chunks) {
+    const total = chunks.reduce((sum, chunk) => sum + chunk.length, 0);
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, offset);
+        offset += chunk.length;
+    }
+    return out;
+}

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

@@ -0,0 +1,81 @@
+import type { Workbook } from '../../core/workbook.ts';
+import type { Worksheet } from '../../core/worksheet.ts';
+import { StyleRegistry } from './styles.ts';
+import { type FlushedSheet } from './worksheet-xml.ts';
+export { buildColumnDefaults, Extent, type FlushedSheet, type RowRenderContext, renderRow, } from './worksheet-xml.ts';
+/** Options controlling how {@link writeXlsx} serialises a workbook. */
+export interface WriteOptions {
+    /**
+     * Pool plain string cell values into a shared-strings table (`xl/sharedStrings.xml`) that cells
+     * reference by index, rather than storing each string inline in its cell. Deduplicates repeated
+     * text and matches Excel's own storage; off by default, which keeps strings inline and omits the
+     * part. Rich-text values stay inline regardless, so their run formatting is unaffected.
+     */
+    readonly useSharedStrings?: boolean;
+}
+/**
+ * {@link WriteOptions} plus the streaming writer's internal wiring, so a buffered caller's options
+ * object can never carry fields meant only for {@link WorkbookStreamWriter}'s own use. Not exported
+ * from the public barrel — {@link buildPackageParts} is the only consumer outside this module.
+ */
+export interface InternalWriteOptions extends WriteOptions {
+    /**
+     * The style registry to intern into, in place of a freshly-seeded one. The streaming writer
+     * serialises each committed row eagerly (freeing its cells), so those rows' style ids must be
+     * assigned by the very same registry that later emits `xl/styles.xml` — otherwise the ids in the
+     * pre-rendered rows would not match the styles part. When omitted the buffered path seeds its own,
+     * so its output is unchanged.
+     */
+    readonly styles?: StyleRegistry;
+    /**
+     * Per-sheet rows already serialised and evicted from the model by the streaming writer, keyed by
+     * the model worksheet. Their XML is emitted ahead of the sheet's remaining live rows and their
+     * extent folds into `<dimension>`. Absent for the buffered path, which holds every row live.
+     */
+    readonly flushed?: ReadonlyMap<Worksheet, FlushedSheet>;
+}
+/**
+ * Serialise a workbook into an `.xlsx` package.
+ *
+ * @throws {@link AuthoringError} if the workbook has no worksheets (a zero-sheet package is corrupt),
+ *   or holds a value the writer cannot yet represent.
+ */
+export declare function writeXlsx(workbook: Workbook, options?: WriteOptions): Uint8Array;
+/**
+ * Serialise a workbook into an `.xlsx` package, deflating off the calling thread.
+ *
+ * Produces the same package {@link writeXlsx} does — every part compresses to identical bytes — and
+ * exists for one reason: DEFLATE dominates the cost of writing a large workbook, and {@link writeXlsx}
+ * spends all of it on the caller's thread. Here `fflate` deflates each part in a worker, so the event
+ * loop keeps turning (stalls drop from the whole write to tens of milliseconds) and parts compress in
+ * parallel, which on a multi-sheet workbook also finishes sooner. On a single-sheet workbook there is
+ * only one part to deflate, so expect responsiveness rather than speed.
+ *
+ * Building the parts still happens on the calling thread — only compression moves. That is why there
+ * is no `readXlsxAsync` mirroring this: reading is dominated by XML parsing and model building, which
+ * no worker can take, and the reader's zip-bomb ceiling is enforced by counting output between
+ * synchronous input slices. See ADR-0024.
+ *
+ * @throws {@link AuthoringError} — as a rejection — under the same conditions as {@link writeXlsx};
+ *   the part-building it shares happens before any worker is involved. A failure raised by the zip
+ *   layer itself (including an environment that cannot spawn a worker) propagates unwrapped, exactly
+ *   as it does from {@link writeXlsx}.
+ */
+export declare function writeXlsxAsync(workbook: Workbook, options?: WriteOptions): Promise<Uint8Array>;
+/**
+ * A style registry seeded from a workbook's read-in style layers (differential styles, named cell
+ * styles, custom indexed palette), ready to intern authored styles after them. Both the buffered
+ * pass and the streaming writer build their registry through here so a cell's style id means the
+ * same thing whichever writer emits it.
+ */
+export declare function createStyleRegistry(workbook: Workbook): StyleRegistry;
+/**
+ * Assemble a workbook into the map of OPC package parts (part name → bytes) that make up an `.xlsx`,
+ * short of zipping them. This is the whole serialisation — content types, relationships, workbook,
+ * per-sheet XML, styles, theme, media, tables, and props — factored out of {@link writeXlsx} so the
+ * streaming writer can drive the identical parts through a streamed zip container rather than
+ * `zipSync`. Neither writer duplicates a byte of serialisation.
+ *
+ * @throws {@link AuthoringError} if the workbook has no worksheets, or holds a value the writer cannot represent.
+ */
+export declare function buildPackageParts(workbook: Workbook, options?: InternalWriteOptions): Record<string, Uint8Array>;