@shbernal/ts-xlsx 2.1.0 → 3.1.0

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,10 +209,25 @@ 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
+     * awaiting its own sink, therefore sees an `error` rather than waiting on a stream that will never
+     * 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 {};

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

@@ -6,9 +6,12 @@ import { encodeAddress, tryDecodeCellRef } 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 { AuthoringError, quoted } from '../../errors.js';
 import { FIXED_ENTRY_MTIME } from '../opc/zip-mtime.js';
-import { buildColumnDefaults, buildPackageParts, createStyleRegistry, Extent, renderRow, } from './write.js';
+import { collectNotes } from './comments.js';
+import { collectHyperlinks } from './hyperlinks.js';
+import { buildColumnDefaults, Extent, renderRow, } from './row-xml.js';
+import { buildPackageParts, createStyleRegistry } from './write.js';
 export class StreamedRow {
     #cells;
     #sheet;
@@ -26,7 +29,7 @@ export class StreamedRow {
         if (this.#committed)
             return;
         this.#committed = true;
-        this.#sheet?.flushRow(this.#number, this.#cells);
+        this.#sheet?.[INTERNAL].flushRow(this.#number, this.#cells);
     }
 }
 export class WorksheetStreamWriter {
@@ -39,12 +42,21 @@ export class WorksheetStreamWriter {
     #flushedRows = [];
     #flushedNumbers = new Set();
     #extent = new Extent();
-    #maxRowOutlineLevel = 0;
-    constructor(sheet, eager, styles) {
+    #rowOutline = new Map();
+    #hyperlinks = [];
+    #notes = [];
+    #dateEpoch;
+    constructor(sheet, eager, styles, dateEpoch) {
         this.#sheet = sheet;
         this.#eager = eager;
         this.#styles = styles;
+        this.#dateEpoch = dateEpoch;
     }
+    static [INTERNAL] = {
+        create(sheet, eager, styles, dateEpoch) {
+            return new WorksheetStreamWriter(sheet, eager, styles, dateEpoch);
+        },
+    };
     get name() {
         return this.#sheet.name;
     }
@@ -77,45 +89,53 @@ export class WorksheetStreamWriter {
         });
         return cells;
     }
-    flushRow(number, cells) {
+    #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 ` +
+                throw new AuthoringError(`row ${number} of streamed sheet ${quoted(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;
-        this.#maxRowOutlineLevel = Math.max(this.#maxRowOutlineLevel, properties?.outlineLevel ?? 0);
-        const { xml, minCol, maxCol } = renderRow({ number, cells, properties }, {
+        this.#rowOutline.set(number, {
+            outlineLevel: properties?.outlineLevel ?? 0,
+            hidden: properties?.hidden ?? false,
+        });
+        this.#hyperlinks.push(...collectHyperlinks(cells));
+        this.#notes.push(...collectNotes(cells));
+        const { xml, attrs, minCol, maxCol } = renderRow({ number, cells, properties }, {
             columnDefaults: this.#columnDefaults,
             styles: this.#styles,
             sharedStrings: null,
             sharedRoles: new Map(),
             collapsedSummaries: new Set(),
+            dateEpoch: this.#dateEpoch,
         });
         if (xml !== '') {
-            this.#flushedRows.push({ number, xml });
+            this.#flushedRows.push({ number, xml, attrs });
             this.#extent.add(number, minCol, maxCol);
         }
         this.#flushedNumbers.add(number);
         this.#sheet[INTERNAL].evictRow(number);
     }
-    flushedSheet() {
+    #flushedSheet() {
         if (this.#flushedRows.length === 0)
             return undefined;
         return {
             rows: this.#flushedRows,
             extent: this.#extent,
-            maxRowOutlineLevel: this.#maxRowOutlineLevel,
+            rowOutline: this.#rowOutline,
+            hyperlinks: this.#hyperlinks,
+            notes: this.#notes,
         };
     }
     getCell(reference) {
         this.#assertOpen();
         const target = tryDecodeCellRef(reference);
         if (target !== undefined && this.#flushedNumbers.has(target.row)) {
-            throw new AuthoringError(`cell ${reference} of streamed sheet "${this.#sheet.name}" is in row ${target.row}, which is ` +
+            throw new AuthoringError(`cell ${reference} of streamed sheet ${quoted(this.#sheet.name)} is in row ${target.row}, which is ` +
                 'already committed: its bytes are written and its cells released, so this value could only ' +
                 'be emitted as a second row with that number. Style a row before committing it.');
         }
@@ -153,9 +173,15 @@ export class WorksheetStreamWriter {
     get model() {
         return this.#sheet;
     }
+    [INTERNAL] = {
+        flushRow: (number, cells) => {
+            this.#flushRow(number, cells);
+        },
+        flushedSheet: () => this.#flushedSheet(),
+    };
     #assertOpen() {
         if (this.#committed) {
-            throw new AuthoringError(`worksheet "${this.#sheet.name}" is already committed: its rows are finalised and no more can be added`);
+            throw new AuthoringError(`worksheet ${quoted(this.#sheet.name)} is already committed: its rows are finalised and no more can be added`);
         }
     }
 }
@@ -172,6 +198,8 @@ export class WorkbookStreamWriter {
     constructor(options = {}) {
         this.#writeOptions = { useSharedStrings: options.useSharedStrings ?? false };
         this.#eager = !this.#writeOptions.useSharedStrings;
+        if (options.dateEpoch !== undefined)
+            this.#workbook.dateEpoch = options.dateEpoch;
         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');
@@ -187,23 +215,17 @@ export class WorkbookStreamWriter {
         return this.#stream;
     }
     addImage(options) {
-        if (this.#committed) {
-            throw new AuthoringError('the workbook is already committed: no more images can be registered');
-        }
+        this.#assertOpen('no more images can be registered');
         return this.#workbook.addImage(options);
     }
     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.#assertOpen('no more worksheets can be added');
+        const sheet = WorksheetStreamWriter[INTERNAL].create(this.#workbook.addWorksheet(name, options), this.#eager, this.#styles, this.#workbook.dateEpoch);
         this.#sheets.push(sheet);
         return sheet;
     }
     async commit() {
-        if (this.#committed) {
-            throw new AuthoringError('the workbook is already committed');
-        }
+        this.#assertOpen('its package is already assembled and cannot be re-emitted');
         this.#committed = true;
         for (const sheet of this.#sheets)
             sheet.commit();
@@ -211,26 +233,41 @@ export class WorkbookStreamWriter {
             this.#workbook.fullCalcOnLoad = true;
         const flushed = new Map();
         for (const sheet of this.#sheets) {
-            const sheetFlushed = sheet.flushedSheet();
+            const sheetFlushed = sheet[INTERNAL].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;
+        const collect = sink === undefined || owned !== undefined;
         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;
+        try {
+            const parts = buildPackageParts(this.#workbook, {
+                ...this.#writeOptions,
+                styles: this.#styles,
+                flushed,
+            });
+            const bytes = await streamZipPackage(parts, (chunk) => {
+                owned?.write(chunk);
+                sink?.write(chunk);
+            }, collect);
+            owned?.end();
+            sink?.end();
+            await sinkSettled;
+            return bytes;
+        }
+        catch (error) {
+            const failure = error instanceof Error ? error : new Error(String(error));
+            sinkSettled?.catch(() => { });
+            owned?.destroy(failure);
+            sink?.destroy(failure);
+            throw error;
+        }
+    }
+    #assertOpen(what) {
+        if (this.#committed) {
+            throw new AuthoringError(`the workbook is already committed: ${what}`);
+        }
     }
 }
 function settleOnFinish(sink) {
@@ -239,7 +276,7 @@ function settleOnFinish(sink) {
         sink.once('error', reject);
     });
 }
-function streamZipPackage(parts, onChunk) {
+function streamZipPackage(parts, onChunk, collect) {
     return new Promise((resolve, reject) => {
         const collected = [];
         const zip = new Zip((err, chunk, final) => {
@@ -247,10 +284,11 @@ function streamZipPackage(parts, onChunk) {
                 reject(err);
                 return;
             }
-            collected.push(chunk);
+            if (collect)
+                collected.push(chunk);
             onChunk(chunk);
             if (final)
-                resolve(concat(collected));
+                resolve(collect ? concat(collected) : undefined);
         });
         for (const [name, data] of Object.entries(parts)) {
             const entry = new ZipDeflate(name, { level: 6 });

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

@@ -1,8 +1,7 @@
 import type { Workbook } from '../../core/workbook.ts';
 import type { Worksheet } from '../../core/worksheet.ts';
+import type { FlushedSheet } from './row-xml.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 {
     /**
@@ -81,6 +80,11 @@ export declare function createStyleRegistry(workbook: Workbook): StyleRegistry;
  * streaming writer can drive the identical parts through a streamed zip container rather than
  * `zipSync`. Neither writer duplicates a byte of serialisation.
  *
+ * Three steps, and their order is load-bearing. The package is planned in full before anything is
+ * serialised, so a drawing's embed and a pivot's cache can target a part number that already exists.
+ * The sheets are serialised before the parts are emitted, because interning a style is a side effect
+ * of that pass and `xl/styles.xml` is one of the parts emitted in the third step.
+ *
  * @throws {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>;