@shbernal/ts-xlsx 3.0.0 → 3.2.0

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

@@ -3,12 +3,17 @@ import { PassThrough } from 'node:stream';
 import { Zip, ZipDeflate } from 'fflate';
 import { concat } from '../../bytes.js';
 import { encodeAddress, tryDecodeCellRef } from '../../core/address.js';
+import { formulaPlacement } from '../../core/array-formula-ranges.js';
+import { formulaNamesInScope } from '../../core/formula.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 { Workbook, } from '../../core/workbook.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 { WorkbookMetadataTable } from './cell-metadata.js';
+import { collectNotes } from './comments.js';
+import { buildColumnDefaults, Extent, renderRow, } from './row-xml.js';
+import { buildPackageParts, createStyleRegistry } from './write.js';
 export class StreamedRow {
     #cells;
     #sheet;
@@ -19,6 +24,11 @@ export class StreamedRow {
         this.#sheet = sheet;
         this.#number = number;
     }
+    static [INTERNAL] = {
+        create(cells, sheet, number) {
+            return new StreamedRow(cells, sheet, number);
+        },
+    };
     get cells() {
         return this.#cells;
     }
@@ -26,7 +36,7 @@ export class StreamedRow {
         if (this.#committed)
             return;
         this.#committed = true;
-        this.#sheet?.flushRow(this.#number, this.#cells);
+        this.#sheet?.[INTERNAL].flushRow(this.#number);
     }
 }
 export class WorksheetStreamWriter {
@@ -39,12 +49,25 @@ export class WorksheetStreamWriter {
     #flushedRows = [];
     #flushedNumbers = new Set();
     #extent = new Extent();
-    #maxRowOutlineLevel = 0;
-    constructor(sheet, eager, styles) {
+    #rowOutline = new Map();
+    #notes = [];
+    #formulas = [];
+    #dateEpoch;
+    #definedNames;
+    #cellMetadata;
+    constructor(sheet, eager, styles, cellMetadata, dateEpoch, definedNames) {
         this.#sheet = sheet;
         this.#eager = eager;
         this.#styles = styles;
+        this.#cellMetadata = cellMetadata;
+        this.#dateEpoch = dateEpoch;
+        this.#definedNames = definedNames;
     }
+    static [INTERNAL] = {
+        create(sheet, eager, styles, cellMetadata, dateEpoch, definedNames) {
+            return new WorksheetStreamWriter(sheet, eager, styles, cellMetadata, dateEpoch, definedNames);
+        },
+    };
     get name() {
         return this.#sheet.name;
     }
@@ -54,14 +77,14 @@ export class WorksheetStreamWriter {
     addRow(values) {
         this.#assertOpen();
         if (!this.#eager)
-            return new StreamedRow(this.#sheet.addRow(values), null, 0);
+            return StreamedRow[INTERNAL].create(this.#sheet.addRow(values), null, 0);
         const number = this.#nextRowNumber();
-        return new StreamedRow(this.#placeRow(number, values), this, number);
+        return StreamedRow[INTERNAL].create(this.#placeRow(number, values), this, number);
     }
     addRows(rows) {
         this.#assertOpen();
         if (!this.#eager)
-            return this.#sheet.addRows(rows).map((cells) => new StreamedRow(cells, null, 0));
+            return this.#sheet.addRows(rows).map((cells) => StreamedRow[INTERNAL].create(cells, null, 0));
         return rows.map((values) => this.addRow(values));
     }
     #nextRowNumber() {
@@ -77,45 +100,61 @@ export class WorksheetStreamWriter {
         });
         return cells;
     }
-    flushRow(number, cells) {
+    #flushRow(number) {
+        const row = this.#sheet.getRow(number);
+        const { cells } = row;
         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 }, {
+        const { properties } = row;
+        this.#rowOutline.set(number, {
+            outlineLevel: properties?.outlineLevel ?? 0,
+            hidden: properties?.hidden ?? false,
+        });
+        this.#notes.push(...collectNotes(cells));
+        for (const cell of cells) {
+            const placement = formulaPlacement(cell.address, cell.col, cell.row, cell.value);
+            if (placement !== undefined)
+                this.#formulas.push(placement);
+        }
+        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,
+            formulaNames: formulaNamesInScope(this.#definedNames, this.#sheet.name),
+            cellMetadata: this.#cellMetadata,
         });
         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,
+            notes: this.#notes,
+            formulas: this.#formulas,
         };
     }
     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.');
         }
@@ -125,6 +164,10 @@ export class WorksheetStreamWriter {
         this.#assertOpen();
         this.#sheet.addDataValidation(sqref, rule, options);
     }
+    addHyperlink(link) {
+        this.#assertOpen();
+        this.#sheet.addHyperlink(link);
+    }
     addConditionalFormatting(formatting) {
         this.#assertOpen();
         this.#sheet.addConditionalFormatting(formatting);
@@ -153,9 +196,15 @@ export class WorksheetStreamWriter {
     get model() {
         return this.#sheet;
     }
+    [INTERNAL] = {
+        flushRow: (number) => {
+            this.#flushRow(number);
+        },
+        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`);
         }
     }
 }
@@ -165,6 +214,7 @@ export class WorkbookStreamWriter {
     #writeOptions;
     #sink;
     #styles;
+    #cellMetadata = new WorkbookMetadataTable();
     #eager;
     #stream;
     #committed = false;
@@ -172,6 +222,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');
@@ -192,7 +244,7 @@ export class WorkbookStreamWriter {
     }
     addWorksheet(name, options = {}) {
         this.#assertOpen('no more worksheets can be added');
-        const sheet = new WorksheetStreamWriter(this.#workbook.addWorksheet(name, options), this.#eager, this.#styles);
+        const sheet = WorksheetStreamWriter[INTERNAL].create(this.#workbook.addWorksheet(name, options), this.#eager, this.#styles, this.#cellMetadata, this.#workbook.dateEpoch, this.#workbook.definedNames);
         this.#sheets.push(sheet);
         return sheet;
     }
@@ -205,23 +257,25 @@ 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 owned = this.#stream;
         const sink = this.#sink;
+        const collect = sink === undefined || owned !== undefined;
         const sinkSettled = sink ? settleOnFinish(sink) : undefined;
         try {
             const parts = buildPackageParts(this.#workbook, {
                 ...this.#writeOptions,
                 styles: this.#styles,
+                cellMetadata: this.#cellMetadata,
                 flushed,
             });
             const bytes = await streamZipPackage(parts, (chunk) => {
                 owned?.write(chunk);
                 sink?.write(chunk);
-            });
+            }, collect);
             owned?.end();
             sink?.end();
             await sinkSettled;
@@ -247,7 +301,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) => {
@@ -255,10 +309,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,15 +1,15 @@
 import type { Workbook } from '../../core/workbook.ts';
 import type { Worksheet } from '../../core/worksheet.ts';
+import { WorkbookMetadataTable } from './cell-metadata.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 {
     /**
-     * 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.
+     * Pool string and rich-text cell values into a shared-strings table (`xl/sharedStrings.xml`) that
+     * cells reference by index, rather than storing each inline in its cell. Deduplicates repeated text
+     * and matches Excel's own storage; a rich value is pooled as a `<si>` of its runs, so its formatting
+     * survives. Off by default, which keeps strings inline and omits the part.
      */
     readonly useSharedStrings?: boolean;
 }
@@ -28,6 +28,12 @@ export interface InternalWriteOptions extends WriteOptions {
      * so its output is unchanged.
      */
     readonly styles?: StyleRegistry;
+    /**
+     * The workbook metadata to record into, in place of a fresh table, for the reason {@link styles} is
+     * shared: a row the streaming writer rendered eagerly may already point a dynamic-array formula or a
+     * rich-value error at the parts this table decides whether to emit.
+     */
+    readonly cellMetadata?: WorkbookMetadataTable;
     /**
      * 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