exceljs-lts 4.5.3 → 4.5.5

package/index.d.ts

@@ -1,4 +1,24 @@
-declare interface Buffer extends ArrayBuffer { }
+/**
+ * Node's Buffer type when @types/node is loaded, otherwise never.
+ * Read through `typeof globalThis` so these typings do not require @types/node.
+ * Newer @types/node declare `var Buffer`; older ones (class Buffer) expose it as `global.Buffer`.
+ */
+type NodeBufferType = typeof globalThis extends { Buffer: { alloc(size: number): infer B } }
+	? B
+	: typeof globalThis extends { global: { Buffer: { alloc(size: number): infer B } } }
+		? B
+		: never;
+
+/**
+ * Binary data returned by writeBuffer(): a Node Buffer when @types/node is loaded
+ * (which is what Node returns at runtime), otherwise ArrayBuffer.
+ */
+declare type Buffer = [NodeBufferType] extends [never] ? ArrayBuffer : NodeBufferType;
+
+/**
+ * Binary data accepted by xlsx.load().
+ */
+type BufferInput = Buffer | ArrayBuffer | Uint8Array;
 
 export declare enum RelationshipType {
 	None = 0,
@@ -830,10 +850,14 @@ export interface PageSetup {
 export interface HeaderFooter {
 	/**
 	 * Set the value of differentFirst as true, which indicates that headers/footers for first page are different from the other pages, `false` by default
+	 *
+	 * Must be `true` for `firstHeader`/`firstFooter` to take effect.
 	 */
 	differentFirst: boolean,
 	/**
 	 * Set the value of differentOddEven as true, which indicates that headers/footers for odd and even pages are different, `false` by default
+	 *
+	 * Must be `true` for `evenHeader`/`evenFooter` to take effect.
 	 */
 	differentOddEven: boolean,
 	/**
@@ -846,18 +870,26 @@ export interface HeaderFooter {
 	oddFooter: string,
 	/**
 	 * Set header string for even pages, could format the string and `null` by default
+	 *
+	 * Only used when `differentOddEven` is `true`; otherwise Excel ignores it.
 	 */
 	evenHeader: string,
 	/**
 	 * Set footer string for even pages, could format the string and `null` by default
+	 *
+	 * Only used when `differentOddEven` is `true`; otherwise Excel ignores it.
 	 */
 	evenFooter: string,
 	/**
 	 * Set header string for the first page, could format the string and `null` by default
+	 *
+	 * Only used when `differentFirst` is `true`; otherwise Excel ignores it.
 	 */
 	firstHeader: string,
 	/**
 	 * Set footer string for the first page, could format the string and `null` by default
+	 *
+	 * Only used when `differentFirst` is `true`; otherwise Excel ignores it.
 	 */
 	firstFooter: string
 }
@@ -865,6 +897,10 @@ export interface HeaderFooter {
 export type AutoFilter = string | {
 	from: string | { row: number; column: number };
 	to: string | { row: number; column: number };
+	/**
+	 * Columns (0 = leftmost column of the range) whose filter button is hidden
+	 */
+	exclude?: number[];
 };
 
 export interface WorksheetProtection {
@@ -889,7 +925,7 @@ export interface Image {
 	extension: 'jpeg' | 'png' | 'gif';
 	base64?: string;
 	filename?: string;
-	buffer?: Buffer;
+	buffer?: Buffer | ArrayBuffer;
 }
 export interface IAnchor {
 	col: number;
@@ -1494,7 +1530,7 @@ export interface Xlsx {
 	 * load from an array buffer
 	 * @param buffer
 	 */
-	load(buffer: Buffer, options?: Partial<XlsxReadOptions>): Promise<Workbook>;
+	load(buffer: BufferInput, options?: Partial<XlsxReadOptions>): Promise<Workbook>;
 
 	/**
 	 * write to a buffer
@@ -1989,6 +2025,7 @@ export namespace stream {
 			addThemes(): Promise<void>;
 			addOfficeRels(): Promise<void>;
 			addContentTypes(): Promise<void>;
+			addDrawings(): Promise<void>;
 			addApp(): Promise<void>;
 			addCore(): Promise<void>;
 			addSharedStrings(): Promise<void>;

package/lib/doc/cell.js

@@ -4,6 +4,7 @@ const _ = require('../utils/under-dash');
 const Enums = require('./enums');
 const {slideFormula} = require('../utils/shared-formula');
 const Note = require('./note');
+const {copyStyle} = require('../utils/copy-style');
 // Cell requirements
 //  Operate inside a worksheet
 //  Store and retrieve a value with a range of types: text, number, date, hyperlink, reference, formula, etc.
@@ -39,7 +40,8 @@ class Cell {
 
   // help GC by removing cyclic (and other) references
   destroy() {
-    delete this.style;
+    delete this._style;
+    delete this._styleShared;
     delete this._value;
     delete this._row;
     delete this._column;
@@ -48,8 +50,31 @@ class Cell {
 
   // =========================================================================
   // Styles stuff
+
+  // Cells loaded from a file share one style object per xf. The object is only
+  // copied when the style is handed out (cell.style), so code that mutates it
+  // in place (cell.style.fill = ...) changes this cell alone.
+  get style() {
+    if (this._styleShared) {
+      this._style = copyStyle(this._style);
+      this._styleShared = false;
+    }
+    return this._style;
+  }
+
+  set style(value) {
+    this._style = value;
+    this._styleShared = false;
+  }
+
+  // use a style object that other cells may share (e.g. a cached xf style)
+  _setSharedStyle(style) {
+    this._style = style;
+    this._styleShared = true;
+  }
+
   get numFmt() {
-    return this.style.numFmt;
+    return this._style.numFmt;
   }
 
   set numFmt(value) {
@@ -57,7 +82,7 @@ class Cell {
   }
 
   get font() {
-    return this.style.font;
+    return this._style.font;
   }
 
   set font(value) {
@@ -65,7 +90,7 @@ class Cell {
   }
 
   get alignment() {
-    return this.style.alignment;
+    return this._style.alignment;
   }
 
   set alignment(value) {
@@ -73,7 +98,7 @@ class Cell {
   }
 
   get border() {
-    return this.style.border;
+    return this._style.border;
   }
 
   set border(value) {
@@ -81,7 +106,7 @@ class Cell {
   }
 
   get fill() {
-    return this.style.fill;
+    return this._style.fill;
   }
 
   set fill(value) {
@@ -89,7 +114,7 @@ class Cell {
   }
 
   get protection() {
-    return this.style.protection;
+    return this._style.protection;
   }
 
   set protection(value) {
@@ -99,7 +124,7 @@ class Cell {
   _setStyle(name, value) {
     // style objects can be shared (e.g. by every cell loaded with the same xf),
     // so never mutate one in place; give this cell a new object instead
-    const oldStyle = this.style;
+    const oldStyle = this._style;
     const style = {...oldStyle, [name]: value};
     this.style = style;
 
@@ -112,12 +137,12 @@ class Cell {
       (Array.isArray(merges)
         ? merges.find(merge => merge.top === master.row && merge.left === master.col)
         : merges[master.address]);
-    if (range && (master === this || master.style === oldStyle)) {
+    if (range && (master === this || master._style === oldStyle)) {
       for (let r = range.top; r <= range.bottom; r++) {
         const row = this.worksheet.findRow(r);
         for (let c = range.left; row && c <= range.right; c++) {
           const cell = row.findCell(c);
-          if (cell && cell.style === oldStyle) {
+          if (cell && cell._style === oldStyle) {
             cell.style = style;
           }
         }
@@ -357,7 +382,7 @@ class Cell {
 
   get model() {
     const {model} = this._value;
-    model.style = this.style;
+    model.style = this._style;
     if (this._comment) {
       model.comment = this._comment.model;
     }
@@ -378,7 +403,7 @@ class Cell {
     }
 
     if (value.style) {
-      this.style = value.style;
+      this._setSharedStyle(value.style);
     } else {
       this.style = {};
     }

package/lib/doc/data-validations.js

@@ -1,19 +1,101 @@
+const colCache = require('../utils/col-cache');
+
+function isRange(address) {
+  return typeof address === 'string' && address.includes(':');
+}
+
 class DataValidations {
   constructor(model) {
     this.model = model || {};
+    // Range-keyed entries (e.g. 'A2:A1048576', kept intact when a file is loaded) are tracked
+    // separately so per-cell add/find stay O(1) when there are none (exceljs#1842).
+    this._ranges = new Map();
+    Object.keys(this.model).forEach(key => {
+      if (isRange(key)) {
+        this._addRange(key);
+      }
+    });
   }
 
   add(address, validation) {
+    if (isRange(address)) {
+      this._addRange(address);
+    } else {
+      this._splitRangeAt(address);
+    }
     return (this.model[address] = validation);
   }
 
   find(address) {
-    return this.model[address];
+    const validation = this.model[address];
+    if (validation !== undefined || isRange(address) || !this._ranges.size) {
+      return validation;
+    }
+    // fall back to range-keyed entries that contain the address
+    const key = this._findRangeKey(address);
+    return key ? this.model[key] : undefined;
   }
 
   remove(address) {
+    if (isRange(address)) {
+      this._ranges.delete(address);
+    } else {
+      this._splitRangeAt(address);
+    }
     this.model[address] = undefined;
   }
+
+  _addRange(key) {
+    if (!this._ranges.has(key)) {
+      this._ranges.set(key, colCache.decodeEx(key));
+    }
+  }
+
+  _findRangeKey(address) {
+    if (!this._ranges.size) {
+      return undefined;
+    }
+    const {row, col} = colCache.decodeAddress(address);
+    for (const [key, {top, left, bottom, right}] of this._ranges) {
+      if (this.model[key] && row >= top && row <= bottom && col >= left && col <= right) {
+        return key;
+      }
+    }
+    return undefined;
+  }
+
+  // If a single cell lies inside a range-keyed entry, replace that entry with up to four
+  // rectangles covering the rest of the range, so the cell can get its own validation
+  // (or none) without overlapping sqrefs.
+  _splitRangeAt(address) {
+    const key = this._findRangeKey(address);
+    if (!key) {
+      return;
+    }
+    const validation = this.model[key];
+    const {row, col} = colCache.decodeAddress(address);
+    const {top, left, bottom, right} = this._ranges.get(key);
+    delete this.model[key];
+    this._ranges.delete(key);
+
+    const addRect = (t, l, b, r) => {
+      if (t > b || l > r) {
+        return;
+      }
+      const tl = colCache.encodeAddress(t, l);
+      if (t === b && l === r) {
+        this.model[tl] = validation;
+      } else {
+        const rangeKey = `${tl}:${colCache.encodeAddress(b, r)}`;
+        this.model[rangeKey] = validation;
+        this._addRange(rangeKey);
+      }
+    };
+    addRect(top, left, row - 1, right); // rows above
+    addRect(row + 1, left, bottom, right); // rows below
+    addRect(row, left, row, col - 1); // left of the cell
+    addRect(row, col + 1, row, right); // right of the cell
+  }
 }
 
 module.exports = DataValidations;

package/lib/doc/image.js

@@ -56,4 +56,36 @@ class Image {
   }
 }
 
+function isFiniteNumber(value) {
+  return typeof value === 'number' && Number.isFinite(value);
+}
+
+Image.validateRange = function validateRange(range) {
+  if (typeof range === 'string') {
+    let decoded;
+    try {
+      decoded = colCache.decode(range);
+    } catch (e) {
+      decoded = {};
+    }
+    const isRange = ['top', 'left', 'bottom', 'right'].every(key => isFiniteNumber(decoded[key]));
+    const isAddress = isFiniteNumber(decoded.row) && isFiniteNumber(decoded.col);
+    if (!isRange && !isAddress) {
+      throw new Error(`Invalid image range "${range}": expected a cell range such as "B2:D6"`);
+    }
+    return;
+  }
+  if (!range || typeof range !== 'object') {
+    throw new Error(
+      'Invalid image range: expected a cell range string or an object with tl and br or ext'
+    );
+  }
+  if (!range.br && !range.ext) {
+    throw new Error('Invalid image range: an object range needs either br or ext');
+  }
+  if (range.ext && typeof range.ext !== 'object') {
+    throw new Error('Invalid image range: ext must be an object with width and height');
+  }
+};
+
 module.exports = Image;

package/lib/doc/worksheet.js

@@ -781,7 +781,15 @@ class Worksheet {
 
   // =========================================================================
   // Images
+  _validateImageId(imageId) {
+    if (imageId === undefined || imageId === null || !this._workbook.getImage(imageId)) {
+      throw new Error(`Image with id ${imageId} not found. Add it with workbook.addImage() first`);
+    }
+  }
+
   addImage(imageId, range) {
+    this._validateImageId(imageId);
+    Image.validateRange(range);
     const model = {
       type: 'image',
       imageId,
@@ -795,6 +803,7 @@ class Worksheet {
   }
 
   addBackgroundImage(imageId) {
+    this._validateImageId(imageId);
     const model = {
       type: 'background',
       imageId,

package/lib/stream/xlsx/workbook-reader.js

@@ -108,7 +108,11 @@ class WorkbookReader extends EventEmitter {
             if (entry.path.match(/xl\/worksheets\/sheet\d+[.]xml/)) {
               match = entry.path.match(/xl\/worksheets\/sheet(\d+)[.]xml/);
               sheetNo = match[1];
-              if (this.sharedStrings && this.workbookRels) {
+              if (
+                this.sharedStrings &&
+                this.workbookRels &&
+                (this.options.styles !== 'cache' || this.stylesParsed)
+              ) {
                 yield* this._parseWorksheet(iterateStream(entry), sheetNo);
               } else {
                 // create temp file for each worksheet
@@ -316,6 +320,7 @@ class WorkbookReader extends EventEmitter {
     if (this.options.styles === 'cache') {
       this.styles = new StyleManager();
       await this.styles.parseStream(iterateStream(entry));
+      this.stylesParsed = true;
     }
   }
 

package/lib/stream/xlsx/workbook-writer.js

@@ -14,6 +14,7 @@ const ContentTypesXform = require('../../xlsx/xform/core/content-types-xform');
 const AppXform = require('../../xlsx/xform/core/app-xform');
 const WorkbookXform = require('../../xlsx/xform/book/workbook-xform');
 const SharedStringsXform = require('../../xlsx/xform/strings/shared-strings-xform');
+const DrawingXform = require('../../xlsx/xform/drawing/drawing-xform');
 
 const WorksheetWriter = require('./worksheet-writer');
 
@@ -45,6 +46,7 @@ class WorkbookWriter {
     this.zipOptions = options.zip;
 
     this.media = [];
+    this.drawings = [];
     this.commentRefs = [];
 
     this.zip = Archiver('zip', this.zipOptions);
@@ -99,6 +101,7 @@ class WorkbookWriter {
     await this.promise;
     await this.addMedia();
     await this._commitWorksheets();
+    await this.addDrawings();
     await Promise.all([
       this.addContentTypes(),
       this.addApp(),
@@ -219,6 +222,7 @@ class WorkbookWriter {
         sharedStrings: this.sharedStrings,
         commentRefs: this.commentRefs,
         media: this.media,
+        drawings: this.drawings,
       };
       const xform = new ContentTypesXform();
       const xml = xform.toXml(model);
@@ -249,6 +253,21 @@ class WorkbookWriter {
     );
   }
 
+  addDrawings() {
+    return new Promise(resolve => {
+      const drawingXform = new DrawingXform();
+      const relsXform = new RelationshipsXform();
+      this.drawings.forEach(drawing => {
+        drawingXform.prepare(drawing, {});
+        this.zip.append(drawingXform.toXml(drawing), {name: `xl/drawings/${drawing.name}.xml`});
+        this.zip.append(relsXform.toXml(drawing.rels), {
+          name: `xl/drawings/_rels/${drawing.name}.xml.rels`,
+        });
+      });
+      resolve();
+    });
+  }
+
   addApp() {
     return new Promise(resolve => {
       const model = {

package/lib/stream/xlsx/worksheet-reader.js

@@ -283,7 +283,7 @@ class WorksheetReader extends EventEmitter {
                   if (c.s) {
                     const style = styles.getStyleModel(c.s);
                     if (style) {
-                      cell.style = style;
+                      cell._setSharedStyle(style);
                     }
                   }
 

package/lib/stream/xlsx/worksheet-writer.js

@@ -13,6 +13,7 @@ const Column = require('../../doc/column');
 const SheetRelsWriter = require('./sheet-rels-writer');
 const SheetCommentsWriter = require('./sheet-comments-writer');
 const DataValidations = require('../../doc/data-validations');
+const Image = require('../../doc/image');
 
 const xmlBuffer = new StringBuf();
 
@@ -246,6 +247,7 @@ class WorksheetWriter {
     this._writePageSetup();
     this._writeHeaderFooter();
     this._writeRowBreaks();
+    this._writeDrawing(); // must be after rowBreaks and before legacyDrawing
 
     // Legacy Data tag for comments
     this._writeLegacyData();
@@ -472,7 +474,34 @@ class WorksheetWriter {
 
   // =========================================================================
 
+  _validateImageId(imageId) {
+    if (imageId === undefined || imageId === null || !this._workbook.getImage(imageId)) {
+      throw new Error(`Image with id ${imageId} not found. Add it with workbook.addImage() first`);
+    }
+  }
+
+  addImage(imageId, range) {
+    if (this.committed) {
+      throw new Error('Cannot add an image to a committed worksheet');
+    }
+    this._validateImageId(imageId);
+    Image.validateRange(range);
+    // Anchors look up column widths and row heights to convert fractional positions.
+    // Only look at what already exists: getRow() would create (and later write) empty rows.
+    const lookup = {
+      properties: this.properties,
+      getColumn: c => this._columns && this._columns[c - 1],
+      getRow: r => this.findRow(r),
+    };
+    this._media.push(new Image(lookup, {type: 'image', imageId, range}));
+  }
+
+  getImages() {
+    return this._media.filter(m => m.type === 'image');
+  }
+
   addBackgroundImage(imageId) {
+    this._validateImageId(imageId);
     this._background = {
       imageId,
     };
@@ -696,6 +725,50 @@ class WorksheetWriter {
     }
   }
 
+  _writeDrawing() {
+    const images = this.getImages();
+    if (!images.length) {
+      return;
+    }
+    const name = `drawing${this.id}`;
+    const rId = this._sheetRelsWriter.addRelationship({
+      Target: `../drawings/${name}.xml`,
+      Type: RelType.Drawing,
+    });
+    const drawing = {rId, name, anchors: [], rels: []};
+    const nextRid = () => `rId${drawing.rels.length + 1}`;
+    const imageRIds = {};
+    images.forEach(image => {
+      const {imageId, range, hyperlinks} = image.model;
+      let imageRId = imageRIds[imageId];
+      if (!imageRId) {
+        imageRId = imageRIds[imageId] = nextRid();
+        drawing.rels.push({
+          Id: imageRId,
+          Type: RelType.Image,
+          Target: `../media/${this._workbook.getImage(imageId).name}`,
+        });
+      }
+      const anchor = {picture: {rId: imageRId}, range};
+      if (hyperlinks && hyperlinks.hyperlink) {
+        const hyperlinkRId = nextRid();
+        anchor.picture.hyperlinks = {tooltip: hyperlinks.tooltip, rId: hyperlinkRId};
+        drawing.rels.push({
+          Id: hyperlinkRId,
+          Type: RelType.Hyperlink,
+          Target: hyperlinks.hyperlink,
+          TargetMode: 'External',
+        });
+      }
+      drawing.anchors.push(anchor);
+    });
+    this._workbook.drawings.push(drawing);
+
+    xmlBuffer.reset();
+    xmlBuffer.addText(`<drawing r:id="${rId}"/>`);
+    this.stream.write(xmlBuffer);
+  }
+
   _writeLegacyData() {
     if (this.hasComments) {
       xmlBuffer.reset();

package/lib/xlsx/rel-type.js

@@ -12,6 +12,7 @@ module.exports = {
   CoreProperties: 'http://schemas.openxmlformats.org/package/2006/relationships/metadata/core-properties',
   ExtenderProperties: 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/extended-properties',
   Comments: 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/comments',
+  Drawing: 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/drawing',
   VmlDrawing: 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/vmlDrawing',
   Table: 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/table',
   PivotCacheDefinition: 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/pivotCacheDefinition',

package/lib/xlsx/xform/sheet/auto-filter-xform.js

@@ -22,16 +22,55 @@ class AutoFilterXform extends BaseXform {
         const firstAddress = getAddress(model.from);
         const secondAddress = getAddress(model.to);
         if (firstAddress && secondAddress) {
-          xmlStream.leafNode('autoFilter', {ref: `${firstAddress}:${secondAddress}`});
+          const ref = `${firstAddress}:${secondAddress}`;
+          if (model.exclude && model.exclude.length) {
+            // hide the filter button on the excluded columns (0 = leftmost column of the range)
+            xmlStream.openNode('autoFilter', {ref});
+            model.exclude.forEach(colId => {
+              xmlStream.leafNode('filterColumn', {colId, hiddenButton: '1'});
+            });
+            xmlStream.closeNode();
+          } else {
+            xmlStream.leafNode('autoFilter', {ref});
+          }
         }
       }
     }
   }
 
   parseOpen(node) {
-    if (node.name === 'autoFilter') {
-      this.model = node.attributes.ref;
+    switch (node.name) {
+      case 'autoFilter':
+        this.ref = node.attributes.ref;
+        this.exclude = [];
+        this.model = this.ref;
+        return true;
+      case 'filterColumn': {
+        const {colId, hiddenButton, showButton} = node.attributes;
+        const hidden =
+          hiddenButton === '1' ||
+          hiddenButton === 'true' ||
+          showButton === '0' ||
+          showButton === 'false';
+        if (hidden && colId !== undefined) {
+          this.exclude.push(parseInt(colId, 10));
+        }
+        return true;
+      }
+      default:
+        return true;
+    }
+  }
+
+  parseClose(name) {
+    if (name === 'autoFilter') {
+      if (this.exclude.length && this.ref) {
+        const [from, to] = this.ref.split(':');
+        this.model = {from, to: to || from, exclude: this.exclude};
+      }
+      return false;
     }
+    return true;
   }
 }
 

package/lib/xlsx/xform/sheet/data-validations-xform.js

@@ -4,6 +4,9 @@ const colCache = require('../../../utils/col-cache');
 const BaseXform = require('../base-xform');
 const Range = require('../../../doc/range');
 
+// sqref ranges with more cells than this are kept as a single range-keyed model entry
+const MAX_EXPANDED_RANGE_CELLS = 1000;
+
 function assign(definedName, attributes, name, defaultValue) {
   const value = attributes[name];
   if (value !== undefined) {
@@ -215,12 +218,20 @@ class DataValidationsXform extends BaseXform {
         }
         // The four known cases: 1. E4:L9 N4:U9  2.E4 L9  3. N4:U9  4. E4
         const list = this._address.split(/\s+/g) || [];
+        // Large ranges (e.g. a whole column 'A2:A1048576') are kept as one range-keyed entry
+        // instead of being expanded into one entry per cell, which could take minutes and
+        // gigabytes (exceljs#1842). DataValidations.find() resolves them. Small ranges are
+        // still expanded so the model keeps its per-cell shape and lookups stay O(1).
         list.forEach(addr => {
           if (addr.includes(':')) {
             const range = new Range(addr);
-            range.forEachAddress(address => {
-              this.model[address] = this._dataValidation;
-            });
+            if (range.count > MAX_EXPANDED_RANGE_CELLS) {
+              this.model[range.range] = this._dataValidation;
+            } else {
+              range.forEachAddress(address => {
+                this.model[address] = this._dataValidation;
+              });
+            }
           } else {
             this.model[addr] = this._dataValidation;
           }