@yuanliwei/exceljs 4.4.0

package/lib/doc/defined-names.js

@@ -0,0 +1,196 @@
+'use strict';
+
+const _ = require('../utils/under-dash');
+const colCache = require('../utils/col-cache');
+const CellMatrix = require('../utils/cell-matrix');
+const Range = require('./range');
+
+const rangeRegexp = /[$](\w+)[$](\d+)(:[$](\w+)[$](\d+))?/;
+
+class DefinedNames {
+  constructor() {
+    this.matrixMap = {};
+  }
+
+  getMatrix(name) {
+    const matrix = this.matrixMap[name] || (this.matrixMap[name] = new CellMatrix());
+    return matrix;
+  }
+
+  // add a name to a cell. locStr in the form SheetName!$col$row or SheetName!$c1$r1:$c2:$r2
+  add(locStr, name) {
+    const location = colCache.decodeEx(locStr);
+    this.addEx(location, name);
+  }
+
+  addEx(location, name) {
+    const matrix = this.getMatrix(name);
+    if (location.top) {
+      for (let col = location.left; col <= location.right; col++) {
+        for (let row = location.top; row <= location.bottom; row++) {
+          const address = {
+            sheetName: location.sheetName,
+            address: colCache.n2l(col) + row,
+            row,
+            col,
+          };
+
+          matrix.addCellEx(address);
+        }
+      }
+    } else {
+      matrix.addCellEx(location);
+    }
+  }
+
+  remove(locStr, name) {
+    const location = colCache.decodeEx(locStr);
+    this.removeEx(location, name);
+  }
+
+  removeEx(location, name) {
+    const matrix = this.getMatrix(name);
+    matrix.removeCellEx(location);
+  }
+
+  removeAllNames(location) {
+    _.each(this.matrixMap, matrix => {
+      matrix.removeCellEx(location);
+    });
+  }
+
+  forEach(callback) {
+    _.each(this.matrixMap, (matrix, name) => {
+      matrix.forEach(cell => {
+        callback(name, cell);
+      });
+    });
+  }
+
+  // get all the names of a cell
+  getNames(addressStr) {
+    return this.getNamesEx(colCache.decodeEx(addressStr));
+  }
+
+  getNamesEx(address) {
+    return _.map(this.matrixMap, (matrix, name) => matrix.findCellEx(address) && name).filter(
+      Boolean
+    );
+  }
+
+  _explore(matrix, cell) {
+    cell.mark = false;
+    const {sheetName} = cell;
+
+    const range = new Range(cell.row, cell.col, cell.row, cell.col, sheetName);
+    let x;
+    let y;
+
+    // grow vertical - only one col to worry about
+    function vGrow(yy, edge) {
+      const c = matrix.findCellAt(sheetName, yy, cell.col);
+      if (!c || !c.mark) {
+        return false;
+      }
+      range[edge] = yy;
+      c.mark = false;
+      return true;
+    }
+    for (y = cell.row - 1; vGrow(y, 'top'); y--);
+    for (y = cell.row + 1; vGrow(y, 'bottom'); y++);
+
+    // grow horizontal - ensure all rows can grow
+    function hGrow(xx, edge) {
+      const cells = [];
+      for (y = range.top; y <= range.bottom; y++) {
+        const c = matrix.findCellAt(sheetName, y, xx);
+        if (c && c.mark) {
+          cells.push(c);
+        } else {
+          return false;
+        }
+      }
+      range[edge] = xx;
+      for (let i = 0; i < cells.length; i++) {
+        cells[i].mark = false;
+      }
+      return true;
+    }
+    for (x = cell.col - 1; hGrow(x, 'left'); x--);
+    for (x = cell.col + 1; hGrow(x, 'right'); x++);
+
+    return range;
+  }
+
+  getRanges(name, matrix) {
+    matrix = matrix || this.matrixMap[name];
+
+    if (!matrix) {
+      return {name, ranges: []};
+    }
+
+    // mark and sweep!
+    matrix.forEach(cell => {
+      cell.mark = true;
+    });
+    const ranges = matrix
+      .map(cell => cell.mark && this._explore(matrix, cell))
+      .filter(Boolean)
+      .map(range => range.$shortRange);
+
+    return {
+      name,
+      ranges,
+    };
+  }
+
+  normaliseMatrix(matrix, sheetName) {
+    // some of the cells might have shifted on specified sheet
+    // need to reassign rows, cols
+    matrix.forEachInSheet(sheetName, (cell, row, col) => {
+      if (cell) {
+        if (cell.row !== row || cell.col !== col) {
+          cell.row = row;
+          cell.col = col;
+          cell.address = colCache.n2l(col) + row;
+        }
+      }
+    });
+  }
+
+  spliceRows(sheetName, start, numDelete, numInsert) {
+    _.each(this.matrixMap, matrix => {
+      matrix.spliceRows(sheetName, start, numDelete, numInsert);
+      this.normaliseMatrix(matrix, sheetName);
+    });
+  }
+
+  spliceColumns(sheetName, start, numDelete, numInsert) {
+    _.each(this.matrixMap, matrix => {
+      matrix.spliceColumns(sheetName, start, numDelete, numInsert);
+      this.normaliseMatrix(matrix, sheetName);
+    });
+  }
+
+  get model() {
+    // To get names per cell - just iterate over all names finding cells if they exist
+    return _.map(this.matrixMap, (matrix, name) => this.getRanges(name, matrix)).filter(
+      definedName => definedName.ranges.length
+    );
+  }
+
+  set model(value) {
+    // value is [ { name, ranges }, ... ]
+    const matrixMap = (this.matrixMap = {});
+    value.forEach(definedName => {
+      const matrix = (matrixMap[definedName.name] = new CellMatrix());
+      definedName.ranges.forEach(rangeStr => {
+        if (rangeRegexp.test(rangeStr.split('!').pop() || '')) {
+          matrix.addCell(rangeStr);
+        }
+      });
+    });
+  }
+}
+
+module.exports = DefinedNames;

package/lib/doc/enums.js

@@ -0,0 +1,48 @@
+'use strict';
+
+module.exports = {
+  ValueType: {
+    Null: 0,
+    Merge: 1,
+    Number: 2,
+    String: 3,
+    Date: 4,
+    Hyperlink: 5,
+    Formula: 6,
+    SharedString: 7,
+    RichText: 8,
+    Boolean: 9,
+    Error: 10,
+  },
+  FormulaType: {
+    None: 0,
+    Master: 1,
+    Shared: 2,
+  },
+  RelationshipType: {
+    None: 0,
+    OfficeDocument: 1,
+    Worksheet: 2,
+    CalcChain: 3,
+    SharedStrings: 4,
+    Styles: 5,
+    Theme: 6,
+    Hyperlink: 7,
+  },
+  DocumentType: {
+    Xlsx: 1,
+  },
+  ReadingOrder: {
+    LeftToRight: 1,
+    RightToLeft: 2,
+  },
+  ErrorValue: {
+    NotApplicable: '#N/A',
+    Ref: '#REF!',
+    Name: '#NAME?',
+    DivZero: '#DIV/0!',
+    Null: '#NULL!',
+    Value: '#VALUE!',
+    Num: '#NUM!',
+  },
+};

package/lib/doc/image.js

@@ -0,0 +1,59 @@
+const colCache = require('../utils/col-cache');
+const Anchor = require('./anchor');
+
+class Image {
+  constructor(worksheet, model) {
+    this.worksheet = worksheet;
+    this.model = model;
+  }
+
+  get model() {
+    switch (this.type) {
+      case 'background':
+        return {
+          type: this.type,
+          imageId: this.imageId,
+        };
+      case 'image':
+        return {
+          type: this.type,
+          imageId: this.imageId,
+          hyperlinks: this.range.hyperlinks,
+          range: {
+            tl: this.range.tl.model,
+            br: this.range.br && this.range.br.model,
+            ext: this.range.ext,
+            editAs: this.range.editAs,
+          },
+        };
+      default:
+        throw new Error('Invalid Image Type');
+    }
+  }
+
+  set model({type, imageId, range, hyperlinks}) {
+    this.type = type;
+    this.imageId = imageId;
+
+    if (type === 'image') {
+      if (typeof range === 'string') {
+        const decoded = colCache.decode(range);
+        this.range = {
+          tl: new Anchor(this.worksheet, {col: decoded.left, row: decoded.top}, -1),
+          br: new Anchor(this.worksheet, {col: decoded.right, row: decoded.bottom}, 0),
+          editAs: 'oneCell',
+        };
+      } else {
+        this.range = {
+          tl: new Anchor(this.worksheet, range.tl, 0),
+          br: range.br && new Anchor(this.worksheet, range.br, 0),
+          ext: range.ext,
+          editAs: range.editAs,
+          hyperlinks: hyperlinks || range.hyperlinks,
+        };
+      }
+    }
+  }
+}
+
+module.exports = Image;

package/lib/doc/modelcontainer.js

@@ -0,0 +1,18 @@
+'use strict';
+
+const XLSX = require('../xlsx/xlsx');
+
+class ModelContainer {
+  constructor(model) {
+    this.model = model;
+  }
+
+  get xlsx() {
+    if (!this._xlsx) {
+      this._xlsx = new XLSX(this);
+    }
+    return this._xlsx;
+  }
+}
+
+module.exports = ModelContainer;

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,132 @@
+const {objectFromProps, range, toSortedArray} = require('../utils/utils');
+
+// TK(2023-10-10): turn this into a class constructor.
+
+function makePivotTable(worksheet, model) {
+  // Example `model`:
+  // {
+  //   // Source of data: the entire sheet range is taken,
+  //   // akin to `worksheet1.getSheetValues()`.
+  //   sourceSheet: worksheet1,
+  //
+  //   // Pivot table fields: values indicate field names;
+  //   // they come from the first row in `worksheet1`.
+  //   rows: ['A', 'B'],
+  //   columns: ['C'],
+  //   values: ['E'], // only 1 item possible for now
+  //   metric: 'sum', // only 'sum' possible for now
+  // }
+
+  validate(worksheet, model);
+
+  const {sourceSheet} = model;
+  let {rows, columns, values} = model;
+
+  const cacheFields = makeCacheFields(sourceSheet, [...rows, ...columns]);
+
+  // let {rows, columns, values} 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]);
+
+  // form pivot table object
+  return {
+    sourceSheet,
+    rows,
+    columns,
+    values,
+    metric: 'sum',
+    cacheFields,
+    // defined in <pivotTableDefinition> of xl/pivotTables/pivotTable1.xml;
+    // also used in xl/workbook.xml
+    cacheId: '10',
+  };
+}
+
+function validate(worksheet, model) {
+  if (worksheet.workbook.pivotTables.length === 1) {
+    throw new Error(
+      'A pivot table was already added. At this time, ExcelJS supports at most one pivot table per file.'
+    );
+  }
+
+  if (model.metric && model.metric !== 'sum') {
+    throw new Error('Only the "sum" metric is supported at this time.');
+  }
+
+  const headerNames = model.sourceSheet.getRow(1).values.slice(1);
+  const isInHeaderNames = objectFromProps(headerNames, true);
+  for (const name of [...model.rows, ...model.columns, ...model.values]) {
+    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.');
+  }
+}
+
+function makeCacheFields(worksheet, fieldNamesWithSharedItems) {
+  // 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'];
+  //
+  // 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(1).values;
+  const nameToHasSharedItems = objectFromProps(fieldNamesWithSharedItems, true);
+
+  const aggregate = columnIndex => {
+    const columnValues = worksheet.getColumn(columnIndex).values.splice(2);
+    const columnValuesAsSet = new Set(columnValues);
+    return toSortedArray(columnValuesAsSet);
+  };
+
+  // make result
+  const result = [];
+  for (const columnIndex of range(1, names.length)) {
+    const name = names[columnIndex];
+    const sharedItems = nameToHasSharedItems[name] ? aggregate(columnIndex) : null;
+    result.push({name, sharedItems});
+  }
+  return result;
+}
+
+module.exports = {makePivotTable};