@lyit/exceljs 4.4.1

package/lib/doc/note.js

@@ -0,0 +1,65 @@
+const _ = require('../utils/under-dash');
+
+class Note {
+  constructor(note) {
+    this.note = note;
+  }
+
+  get model() {
+    let value = null;
+    switch (typeof this.note) {
+      case 'string':
+        value = {
+          type: 'note',
+          note: {
+            texts: [
+              {
+                text: this.note,
+              },
+            ],
+          },
+        };
+        break;
+      default:
+        value = {
+          type: 'note',
+          note: this.note,
+        };
+        break;
+    }
+    // Suitable for all cell comments
+    return _.deepMerge({}, Note.DEFAULT_CONFIGS, value);
+  }
+
+  set model(value) {
+    const {note} = value;
+    const {texts} = note;
+    if (texts.length === 1 && Object.keys(texts[0]).length === 1) {
+      this.note = texts[0].text;
+    } else {
+      this.note = note;
+    }
+  }
+
+  static fromModel(model) {
+    const note = new Note();
+    note.model = model;
+    return note;
+  }
+}
+
+Note.DEFAULT_CONFIGS = {
+  note: {
+    margins: {
+      insetmode: 'auto',
+      inset: [0.13, 0.13, 0.25, 0.25],
+    },
+    protection: {
+      locked: 'True',
+      lockText: 'True',
+    },
+    editAs: 'absolute',
+  },
+};
+
+module.exports = Note;

package/lib/doc/pivot-table.js

@@ -0,0 +1,239 @@
+const colCache = require('../utils/col-cache');
+const {objectFromProps, range, toSortedArray} = require('../utils/utils');
+
+// TK(2023-10-10): turn this into a class constructor.
+
+// IMPORTANT: Pivot tables are NOT supported with streaming API (WorkbookWriter)
+//
+// Pivot tables require reading ALL source data to generate the pivot cache,
+// which conflicts with streaming's one-pass write model. Excel requires complete
+// pivot cache data (all unique values and all data rows) at file creation time.
+//
+// For large datasets, use the standard (non-streaming) Workbook API with pivot tables.
+
+function makePivotTable(worksheet, model) {
+  // Example `model`:
+  // {
+  //   sourceSheet: worksheet1,
+  //   rows: ['A', 'B'],
+  //   columns: ['C'],
+  //   values: ['E'],
+  //   pages: ['F'], // optional
+  //   pageDefaults: { F: 'value' }, // optional
+  //   metric: 'sum', 'count'
+  //   startRow: 1, // optional: header row number (default: 1)
+  //   startCell: 'A1', // optional: pivot table location (default: 'A1')
+  //   valueNumFmt: '#,##0.00', // optional: number format for value field
+  //   verbose: false, // optional: show progress logs
+  // }
+
+  validate(worksheet, model);
+
+  const {sourceSheet} = model;
+  let {rows, columns, values, pages = []} = model;
+  const {metric, pageDefaults = {}, verbose = false} = model;
+  const startRow = model.startRow || 1;
+
+  // Generate sharedItems only for categorical fields (rows, columns, pages).
+  // Value fields (values) are numeric aggregations and should NOT have sharedItems,
+  // as their raw values are written directly as <n> in cache records.
+  // This significantly reduces processing time for wide datasets (e.g. 26 cols × 60k rows).
+  if (verbose) {
+    // eslint-disable-next-line no-console
+    console.log('Generating cache fields...');
+  }
+  const usedFieldNames = [...model.rows, ...model.columns, ...pages];
+  const cacheFields = makeCacheFields(sourceSheet, usedFieldNames, startRow, verbose);
+  if (verbose) {
+    // eslint-disable-next-line no-console
+    console.log(`  ✓ Generated ${cacheFields.length} cache fields (${usedFieldNames.length} with sharedItems)`);
+  }
+
+  // Calculate the source data range for the pivot cache
+  // The range should start from the header row (startRow) to the last row with data
+  const dimensions = sourceSheet.dimensions;
+  const sourceDataRange = dimensions
+    ? colCache.encode(startRow, dimensions.left, dimensions.bottom, dimensions.right)
+    : null;
+
+  // let {rows, columns, values, pages} use indices instead of names;
+  // names can then be accessed via `pivotTable.cacheFields[index].name`.
+  // *Note*: Using `reduce` as `Object.fromEntries` requires Node 12+;
+  // ExcelJS is >=8.3.0 (as of 2023-10-08).
+  const nameToIndex = cacheFields.reduce((result, cacheField, index) => {
+    result[cacheField.name] = index;
+    return result;
+  }, {});
+  rows = rows.map(row => nameToIndex[row]);
+  columns = columns.map(column => nameToIndex[column]);
+  values = values.map(value => nameToIndex[value]);
+  pages = pages.map(page => nameToIndex[page]);
+
+  // Generate unique cache ID based on the number of existing pivot tables
+  // Each pivot table gets its own cache ID (starting from 10)
+  const cacheId = String(10 + worksheet.workbook.pivotTables.length);
+
+  // Convert pageDefaults from field names to indices with item indices
+  const pageDefaultsIndices = {};
+  for (const [fieldName, defaultValue] of Object.entries(pageDefaults)) {
+    const fieldIndex = nameToIndex[fieldName];
+    if (fieldIndex !== undefined) {
+      const cacheField = cacheFields[fieldIndex];
+      if (cacheField.sharedItems) {
+        // Find the item index for the default value
+        const itemIndex = cacheField.sharedItems.findIndex(item => item === defaultValue);
+        if (itemIndex >= 0) {
+          pageDefaultsIndices[fieldIndex] = itemIndex;
+        }
+      }
+    }
+  }
+
+  // form pivot table object
+  return {
+    sourceSheet,
+    rows,
+    columns,
+    values,
+    pages,
+    pageDefaults: pageDefaultsIndices,
+    metric,
+    cacheFields,
+    // defined in <pivotTableDefinition> of xl/pivotTables/pivotTableN.xml;
+    // also used in xl/workbook.xml
+    cacheId,
+    // Control whether pivot table style overrides worksheet column widths
+    // '0' = preserve worksheet column widths (useful for custom sizing)
+    // '1' = apply pivot table style width/height (default Excel behavior)
+    applyWidthHeightFormats:
+      model.applyWidthHeightFormats !== undefined ? model.applyWidthHeightFormats : '1',
+    // Data starts from this row (startRow + 1)
+    dataStartRow: startRow + 1,
+    // Source data range for the pivot cache (from header row to last data row)
+    sourceDataRange,
+    // Pivot table location on the destination sheet
+    startCell: model.startCell || 'A1',
+    // Number format for the value field (e.g. '#,##0.00' for currency)
+    valueNumFmt: model.valueNumFmt || null,
+  };
+}
+
+function validate(worksheet, model) {
+  // Note: Multiple pivot tables are now supported
+
+  if (model.metric && model.metric !== 'sum' && model.metric !== 'count') {
+    throw new Error('Only the "sum" and "count" metric is supported at this time.');
+  }
+
+  const startRow = model.startRow || 1;
+  const headerNames = model.sourceSheet.getRow(startRow).values.slice(1);
+  const isInHeaderNames = objectFromProps(headerNames, true);
+  const pages = model.pages || [];
+  for (const name of [...model.rows, ...model.columns, ...model.values, ...pages]) {
+    if (!isInHeaderNames[name]) {
+      throw new Error(`The header name "${name}" was not found in ${model.sourceSheet.name}.`);
+    }
+  }
+
+  if (!model.rows.length) {
+    throw new Error('No pivot table rows specified.');
+  }
+
+  if (!model.columns.length) {
+    throw new Error('No pivot table columns specified.');
+  }
+
+  if (model.values.length !== 1) {
+    throw new Error('Exactly 1 value needs to be specified at this time.');
+  }
+
+  // Validate page fields don't overlap with rows/columns/values
+  const allFields = [...model.rows, ...model.columns, ...model.values];
+  for (const pageField of pages) {
+    if (allFields.includes(pageField)) {
+      throw new Error(
+        `Page field "${pageField}" cannot also be used as a row, column, or value field.`,
+      );
+    }
+  }
+
+  // Validate pageDefaults reference valid page fields and values
+  if (model.pageDefaults) {
+    for (const [fieldName, defaultValue] of Object.entries(model.pageDefaults)) {
+      if (!pages.includes(fieldName)) {
+        throw new Error(`pageDefaults field "${fieldName}" is not in the pages array.`);
+      }
+    }
+  }
+}
+
+function makeCacheFields(worksheet, fieldNamesWithSharedItems, startRow = 1, verbose = false) {
+  // Cache fields are used in pivot tables to reference source data.
+  //
+  // Example
+  // -------
+  // Turn
+  //
+  //  `worksheet` sheet values [
+  //    ['A', 'B', 'C', 'D', 'E'],
+  //    ['a1', 'b1', 'c1', 4, 5],
+  //    ['a1', 'b2', 'c1', 4, 5],
+  //    ['a2', 'b1', 'c2', 14, 24],
+  //    ['a2', 'b2', 'c2', 24, 35],
+  //    ['a3', 'b1', 'c3', 34, 45],
+  //    ['a3', 'b2', 'c3', 44, 45]
+  //  ];
+  //  fieldNamesWithSharedItems = ['A', 'B', 'C'];
+  //  startRow = 1 (default, header row)
+  //
+  // into
+  //
+  //  [
+  //    { name: 'A', sharedItems: ['a1', 'a2', 'a3'] },
+  //    { name: 'B', sharedItems: ['b1', 'b2'] },
+  //    { name: 'C', sharedItems: ['c1', 'c2', 'c3'] },
+  //    { name: 'D', sharedItems: null },
+  //    { name: 'E', sharedItems: null }
+  //  ]
+
+  const names = worksheet.getRow(startRow).values;
+  const nameToHasSharedItems = objectFromProps(fieldNamesWithSharedItems, true);
+  const totalColumns = names.length - 1;
+
+  const aggregate = (columnIndex, fieldName) => {
+    if (verbose && nameToHasSharedItems[fieldName]) {
+      // eslint-disable-next-line no-console
+      console.log(`    Processing column ${columnIndex}/${totalColumns}: ${fieldName}`);
+    }
+    const columnValues = worksheet.getColumn(columnIndex).values.slice(startRow + 1);
+
+    // Deduplicate case-insensitively for Excel compatibility
+    // Excel treats pivot table values as case-insensitive, so "Apple" and "apple"
+    // are considered the same value. We keep the first occurrence of each case-insensitive variant.
+    const seen = new Map(); // lowercase -> first occurrence
+    const uniqueValues = [];
+
+    for (const value of columnValues) {
+      if (value === null || value === undefined) continue;
+
+      const key = typeof value === 'string' ? value.toLowerCase() : value;
+      if (!seen.has(key)) {
+        seen.set(key, value);
+        uniqueValues.push(value);
+      }
+    }
+
+    return toSortedArray(uniqueValues);
+  };
+
+  // make result
+  const result = [];
+  for (const columnIndex of range(1, names.length)) {
+    const name = names[columnIndex];
+    const sharedItems = nameToHasSharedItems[name] ? aggregate(columnIndex, name) : null;
+    result.push({name, sharedItems});
+  }
+  return result;
+}
+
+module.exports = {makePivotTable};

package/lib/doc/range.js

@@ -0,0 +1,257 @@
+const colCache = require('../utils/col-cache');
+
+// used by worksheet to calculate sheet dimensions
+class Range {
+  constructor() {
+    this.decode(arguments);
+  }
+
+  setTLBR(t, l, b, r, s) {
+    if (arguments.length < 4) {
+      // setTLBR(tl, br, s)
+      const tl = colCache.decodeAddress(t);
+      const br = colCache.decodeAddress(l);
+      this.model = {
+        top: Math.min(tl.row, br.row),
+        left: Math.min(tl.col, br.col),
+        bottom: Math.max(tl.row, br.row),
+        right: Math.max(tl.col, br.col),
+        sheetName: b,
+      };
+
+      this.setTLBR(tl.row, tl.col, br.row, br.col, s);
+    } else {
+      // setTLBR(t, l, b, r, s)
+      this.model = {
+        top: Math.min(t, b),
+        left: Math.min(l, r),
+        bottom: Math.max(t, b),
+        right: Math.max(l, r),
+        sheetName: s,
+      };
+    }
+  }
+
+  decode(argv) {
+    switch (argv.length) {
+      case 5: // [t,l,b,r,s]
+        this.setTLBR(argv[0], argv[1], argv[2], argv[3], argv[4]);
+        break;
+      case 4: // [t,l,b,r]
+        this.setTLBR(argv[0], argv[1], argv[2], argv[3]);
+        break;
+
+      case 3: // [tl,br,s]
+        this.setTLBR(argv[0], argv[1], argv[2]);
+        break;
+      case 2: // [tl,br]
+        this.setTLBR(argv[0], argv[1]);
+        break;
+
+      case 1: {
+        const value = argv[0];
+        if (value instanceof Range) {
+          // copy constructor
+          this.model = {
+            top: value.model.top,
+            left: value.model.left,
+            bottom: value.model.bottom,
+            right: value.model.right,
+            sheetName: value.sheetName,
+          };
+        } else if (value instanceof Array) {
+          // an arguments array
+          this.decode(value);
+        } else if (value.top && value.left && value.bottom && value.right) {
+          // a model
+          this.model = {
+            top: value.top,
+            left: value.left,
+            bottom: value.bottom,
+            right: value.right,
+            sheetName: value.sheetName,
+          };
+        } else {
+          // [sheetName!]tl:br
+          const tlbr = colCache.decodeEx(value);
+          if (tlbr.top) {
+            this.model = {
+              top: tlbr.top,
+              left: tlbr.left,
+              bottom: tlbr.bottom,
+              right: tlbr.right,
+              sheetName: tlbr.sheetName,
+            };
+          } else {
+            this.model = {
+              top: tlbr.row,
+              left: tlbr.col,
+              bottom: tlbr.row,
+              right: tlbr.col,
+              sheetName: tlbr.sheetName,
+            };
+          }
+        }
+        break;
+      }
+
+      case 0:
+        this.model = {
+          top: 0,
+          left: 0,
+          bottom: 0,
+          right: 0,
+        };
+        break;
+
+      default:
+        throw new Error(`Invalid number of arguments to _getDimensions() - ${argv.length}`);
+    }
+  }
+
+  get top() {
+    return this.model.top || 1;
+  }
+
+  set top(value) {
+    this.model.top = value;
+  }
+
+  get left() {
+    return this.model.left || 1;
+  }
+
+  set left(value) {
+    this.model.left = value;
+  }
+
+  get bottom() {
+    return this.model.bottom || 1;
+  }
+
+  set bottom(value) {
+    this.model.bottom = value;
+  }
+
+  get right() {
+    return this.model.right || 1;
+  }
+
+  set right(value) {
+    this.model.right = value;
+  }
+
+  get sheetName() {
+    return this.model.sheetName;
+  }
+
+  set sheetName(value) {
+    this.model.sheetName = value;
+  }
+
+  get _serialisedSheetName() {
+    const {sheetName} = this.model;
+    if (sheetName) {
+      if (/^[a-zA-Z0-9]*$/.test(sheetName)) {
+        return `${sheetName}!`;
+      }
+      return `'${sheetName}'!`;
+    }
+    return '';
+  }
+
+  expand(top, left, bottom, right) {
+    if (!this.model.top || top < this.top) this.top = top;
+    if (!this.model.left || left < this.left) this.left = left;
+    if (!this.model.bottom || bottom > this.bottom) this.bottom = bottom;
+    if (!this.model.right || right > this.right) this.right = right;
+  }
+
+  expandRow(row) {
+    if (row) {
+      const {dimensions, number} = row;
+      if (dimensions) {
+        this.expand(number, dimensions.min, number, dimensions.max);
+      }
+    }
+  }
+
+  expandToAddress(addressStr) {
+    const address = colCache.decodeEx(addressStr);
+    this.expand(address.row, address.col, address.row, address.col);
+  }
+
+  get tl() {
+    return colCache.n2l(this.left) + this.top;
+  }
+
+  get $t$l() {
+    return `$${colCache.n2l(this.left)}$${this.top}`;
+  }
+
+  get br() {
+    return colCache.n2l(this.right) + this.bottom;
+  }
+
+  get $b$r() {
+    return `$${colCache.n2l(this.right)}$${this.bottom}`;
+  }
+
+  get range() {
+    return `${this._serialisedSheetName + this.tl}:${this.br}`;
+  }
+
+  get $range() {
+    return `${this._serialisedSheetName + this.$t$l}:${this.$b$r}`;
+  }
+
+  get shortRange() {
+    return this.count > 1 ? this.range : this._serialisedSheetName + this.tl;
+  }
+
+  get $shortRange() {
+    return this.count > 1 ? this.$range : this._serialisedSheetName + this.$t$l;
+  }
+
+  get count() {
+    return (1 + this.bottom - this.top) * (1 + this.right - this.left);
+  }
+
+  toString() {
+    return this.range;
+  }
+
+  intersects(other) {
+    if (other.sheetName && this.sheetName && other.sheetName !== this.sheetName) return false;
+    if (other.bottom < this.top) return false;
+    if (other.top > this.bottom) return false;
+    if (other.right < this.left) return false;
+    if (other.left > this.right) return false;
+    return true;
+  }
+
+  contains(addressStr) {
+    const address = colCache.decodeEx(addressStr);
+    return this.containsEx(address);
+  }
+
+  containsEx(address) {
+    if (address.sheetName && this.sheetName && address.sheetName !== this.sheetName) return false;
+    return (
+      address.row >= this.top &&
+      address.row <= this.bottom &&
+      address.col >= this.left &&
+      address.col <= this.right
+    );
+  }
+
+  forEachAddress(cb) {
+    for (let col = this.left; col <= this.right; col++) {
+      for (let row = this.top; row <= this.bottom; row++) {
+        cb(colCache.encodeAddress(row, col), row, col);
+      }
+    }
+  }
+}
+
+module.exports = Range;