@cj-tech-master/excelts 1.4.5-canary.20251212064440.3eb099f → 1.4.5-canary.20251212143538.45665af

package/dist/cjs/doc/worksheet.js

@@ -133,14 +133,21 @@ class Worksheet {
         }
         this._name = name;
     }
+    /**
+     * The workbook that contains this worksheet
+     */
     get workbook() {
         return this._workbook;
     }
-    // when you're done with this worksheet, call this to remove from workbook
+    /**
+     * When you're done with this worksheet, call this to remove from workbook
+     */
     destroy() {
         this._workbook.removeWorksheetEx(this);
     }
-    // Get the bounding range of the cells in this worksheet
+    /**
+     * Get the bounding range of the cells in this worksheet
+     */
     get dimensions() {
         const dimensions = new range_js_1.Range();
         this._rows.forEach(row => {
@@ -155,12 +162,18 @@ class Worksheet {
     }
     // =========================================================================
     // Columns
-    // get the current columns array.
+    /**
+     * Get the current columns array
+     */
     get columns() {
         return this._columns;
     }
-    // set the columns from an array of column definitions.
-    // Note: any headers defined will overwrite existing values.
+    /**
+     * Add column headers and define column keys and widths.
+     *
+     * Note: these column structures are a workbook-building convenience only,
+     * apart from the column width, they will not be fully persisted.
+     */
     set columns(value) {
         // calculate max header row count
         this._headerRowCount = value.reduce((pv, cv) => {
@@ -188,7 +201,9 @@ class Worksheet {
     eachColumnKey(f) {
         Object.keys(this._keys).forEach(key => f(this._keys[key], key));
     }
-    // get a single column by col number. If it doesn't exist, create it and any gaps before it
+    /**
+     * Access an individual column by key, letter and 1-based column number
+     */
     getColumn(c) {
         let colNum;
         if (typeof c === "string") {
@@ -214,6 +229,17 @@ class Worksheet {
         }
         return this._columns[colNum - 1];
     }
+    /**
+     * Cut one or more columns (columns to the right are shifted left)
+     * and optionally insert more
+     *
+     * If column properties have been defined, they will be cut or moved accordingly
+     *
+     * Known Issue: If a splice causes any merged cells to move, the results may be unpredictable
+     *
+     * Also: If the worksheet has more rows than values in the column inserts,
+     * the rows will still be shifted as if the values existed
+     */
     spliceColumns(start, count, ...inserts) {
         const rows = this._rows;
         const nRows = rows.length;
@@ -253,9 +279,15 @@ class Worksheet {
         // account for defined names
         this.workbook.definedNames.spliceColumns(this.name, start, count, inserts.length);
     }
+    /**
+     * Get the last column in a worksheet
+     */
     get lastColumn() {
         return this.getColumn(this.columnCount);
     }
+    /**
+     * The total column size of the document. Equal to the maximum cell count from all of the rows
+     */
     get columnCount() {
         let maxCount = 0;
         this.eachRow(row => {
@@ -263,6 +295,9 @@ class Worksheet {
         });
         return maxCount;
     }
+    /**
+     * A count of the number of columns that have values
+     */
     get actualColumnCount() {
         // performance nightmare - for each row, counts all the columns used
         const counts = [];
@@ -294,23 +329,41 @@ class Worksheet {
     get _nextRow() {
         return this._lastRowNumber + 1;
     }
+    /**
+     * Get the last editable row in a worksheet (or undefined if there are none)
+     */
     get lastRow() {
         if (this._rows.length) {
             return this._rows[this._rows.length - 1];
         }
         return undefined;
     }
-    // find a row (if exists) by row number
+    /**
+     * Tries to find and return row for row number, else undefined
+     *
+     * @param r - The 1-indexed row number
+     */
     findRow(r) {
         return this._rows[r - 1];
     }
-    // find multiple rows (if exists) by row number
+    /**
+     * Tries to find and return rows for row number start and length, else undefined
+     *
+     * @param start - The 1-indexed starting row number
+     * @param length - The length of the expected array
+     */
     findRows(start, length) {
         return this._rows.slice(start - 1, start - 1 + length);
     }
+    /**
+     * The total row size of the document. Equal to the row number of the last row that has values.
+     */
     get rowCount() {
         return this._lastRowNumber;
     }
+    /**
+     * A count of the number of rows that have values. If a mid-document row is empty, it will not be included in the count.
+     */
     get actualRowCount() {
         // counts actual rows that have actual data
         let count = 0;
@@ -319,7 +372,9 @@ class Worksheet {
         });
         return count;
     }
-    // get a row by row number.
+    /**
+     * Get or create row by 1-based index
+     */
     getRow(r) {
         let row = this._rows[r - 1];
         if (!row) {
@@ -327,7 +382,9 @@ class Worksheet {
         }
         return row;
     }
-    // get multiple rows by row number.
+    /**
+     * Get or create rows by 1-based index
+     */
     getRows(start, length) {
         if (length < 1) {
             return undefined;
@@ -338,6 +395,10 @@ class Worksheet {
         }
         return rows;
     }
+    /**
+     * Add a couple of Rows by key-value, after the last current row, using the column keys,
+     * or add a row by contiguous Array (assign to columns A, B & C)
+     */
     addRow(value, style = "n") {
         const rowNo = this._nextRow;
         const row = this.getRow(rowNo);
@@ -345,6 +406,9 @@ class Worksheet {
         this._setStyleOption(rowNo, style[0] === "i" ? style : "n");
         return row;
     }
+    /**
+     * Add multiple rows by providing an array of arrays or key-value pairs
+     */
     addRows(value, style = "n") {
         const rows = [];
         value.forEach(row => {
@@ -352,11 +416,19 @@ class Worksheet {
         });
         return rows;
     }
+    /**
+     * Insert a Row by key-value, at the position (shifting down all rows from position),
+     * using the column keys, or add a row by contiguous Array (assign to columns A, B & C)
+     */
     insertRow(pos, value, style = "n") {
         this.spliceRows(pos, 0, value);
         this._setStyleOption(pos, style);
         return this.getRow(pos);
     }
+    /**
+     * Insert multiple rows at position (shifting down all rows from position)
+     * by providing an array of arrays or key-value pairs
+     */
     insertRows(pos, values, style = "n") {
         this.spliceRows(pos, 0, ...values);
         if (style !== "n") {
@@ -390,6 +462,9 @@ class Worksheet {
         });
         rDst.height = rSrc.height;
     }
+    /**
+     * Duplicate rows and insert new rows
+     */
     duplicateRow(rowNum, count, insert = false) {
         // create count duplicates of rowNum
         // either inserting new or overwriting existing rows
@@ -406,6 +481,12 @@ class Worksheet {
             });
         }
     }
+    /**
+     * Cut one or more rows (rows below are shifted up)
+     * and optionally insert more
+     *
+     * Known Issue: If a splice causes any merged cells to move, the results may be unpredictable
+     */
     spliceRows(start, count, ...inserts) {
         // same problem as row.splice, except worse.
         const nKeep = start + count;
@@ -470,26 +551,33 @@ class Worksheet {
         // account for defined names
         this.workbook.definedNames.spliceRows(this.name, start, count, nInserts);
     }
-    eachRow(options, iteratee) {
-        if (!iteratee) {
-            iteratee = options;
-            options = undefined;
+    eachRow(optOrCallback, maybeCallback) {
+        let options;
+        let callback;
+        if (typeof optOrCallback === "function") {
+            callback = optOrCallback;
+        }
+        else {
+            options = optOrCallback;
+            callback = maybeCallback;
         }
         if (options && options.includeEmpty) {
             const n = this._rows.length;
             for (let i = 1; i <= n; i++) {
-                iteratee(this.getRow(i), i);
+                callback(this.getRow(i), i);
             }
         }
         else {
             this._rows.forEach(row => {
                 if (row && row.hasValues) {
-                    iteratee(row, row.number);
+                    callback(row, row.number);
                 }
             });
         }
     }
-    // return all rows as sparse array
+    /**
+     * Return all rows as sparse array
+     */
     getSheetValues() {
         const rows = [];
         this._rows.forEach(row => {
@@ -501,13 +589,17 @@ class Worksheet {
     }
     // =========================================================================
     // Cells
-    // returns the cell at [r,c] or address given by r. If not found, return undefined
+    /**
+     * Returns the cell at [r,c] or address given by r. If not found, return undefined
+     */
     findCell(r, c) {
         const address = col_cache_js_1.colCache.getAddress(r, c);
         const row = this._rows[address.row - 1];
         return row ? row.findCell(address.col) : undefined;
     }
-    // return the cell at [r,c] or address given by r. If not found, create a new one.
+    /**
+     * Get or create cell at [r,c] or address given by r
+     */
     getCell(r, c) {
         const address = col_cache_js_1.colCache.getAddress(r, c);
         const row = this.getRow(address.row);
@@ -515,7 +607,15 @@ class Worksheet {
     }
     // =========================================================================
     // Merge
-    // convert the range defined by ['tl:br'], [tl,br] or [t,l,b,r] into a single 'merged' cell
+    /**
+     * Merge cells, either:
+     *
+     * tlbr string, e.g. `'A4:B5'`
+     *
+     * tl string, br string, e.g. `'G10', 'H11'`
+     *
+     * t, l, b, r numbers, e.g. `10,11,12,13`
+     */
     mergeCells(...cells) {
         const dimensions = new range_js_1.Range(cells);
         this._mergeCellsInternal(dimensions);
@@ -560,9 +660,11 @@ class Worksheet {
         // return true if this._merges has a merge object
         return Object.values(this._merges).some(Boolean);
     }
-    // scan the range defined by ['tl:br'], [tl,br] or [t,l,b,r] and if any cell is part of a merge,
-    // un-merge the group. Note this function can affect multiple merges and merge-blocks are
-    // atomic - either they're all merged or all un-merged.
+    /**
+     * Scan the range and if any cell is part of a merge, un-merge the group.
+     * Note this function can affect multiple merges and merge-blocks are
+     * atomic - either they're all merged or all un-merged.
+     */
     unMergeCells(...cells) {
         const dimensions = new range_js_1.Range(cells);
         // find any cells in that range and unmerge them
@@ -634,6 +736,10 @@ class Worksheet {
     }
     // =========================================================================
     // Images
+    /**
+     * Using the image id from `Workbook.addImage`,
+     * embed an image within the worksheet to cover a range
+     */
     addImage(imageId, range) {
         const model = {
             type: "image",
@@ -645,6 +751,9 @@ class Worksheet {
     getImages() {
         return this._media.filter(m => m.type === "image");
     }
+    /**
+     * Using the image id from `Workbook.addImage`, set the background to the worksheet
+     */
     addBackgroundImage(imageId) {
         const model = {
             type: "background",
@@ -658,6 +767,9 @@ class Worksheet {
     }
     // =========================================================================
     // Worksheet Protection
+    /**
+     * Protect the worksheet with optional password and options
+     */
     protect(password, options) {
         // TODO: make this function truly async
         // perhaps marshal to worker thread or something
@@ -692,17 +804,29 @@ class Worksheet {
     }
     // =========================================================================
     // Tables
+    /**
+     * Add a new table and return a reference to it
+     */
     addTable(model) {
         const table = new table_js_1.Table(this, model);
         this.tables[model.name] = table;
         return table;
     }
+    /**
+     * Fetch table by name
+     */
     getTable(name) {
         return this.tables[name];
     }
+    /**
+     * Delete table by name
+     */
     removeTable(name) {
         delete this.tables[name];
     }
+    /**
+     * Fetch all tables in the worksheet
+     */
     getTables() {
         return Object.values(this.tables);
     }
@@ -718,9 +842,15 @@ Please leave feedback at https://github.com/excelts/excelts/discussions/2575`);
     }
     // ===========================================================================
     // Conditional Formatting
+    /**
+     * Add conditional formatting rules
+     */
     addConditionalFormatting(cf) {
         this.conditionalFormattings.push(cf);
     }
+    /**
+     * Delete conditional formatting rules
+     */
     removeConditionalFormatting(filter) {
         if (typeof filter === "number") {
             this.conditionalFormattings.splice(filter, 1);

package/dist/esm/doc/column.js

@@ -2,9 +2,11 @@ import { colCache } from "../utils/col-cache.js";
 import { isEqual } from "../utils/under-dash.js";
 import { Enums } from "./enums.js";
 const DEFAULT_COLUMN_WIDTH = 9;
-// Column defines the column properties for 1 column.
-// This includes header rows, widths, key, (style), etc.
-// Worksheet will condense the columns as appropriate during serialization
+/**
+ * Column defines the column properties for 1 column.
+ * This includes header rows, widths, key, (style), etc.
+ * Worksheet will condense the columns as appropriate during serialization
+ */
 class Column {
     constructor(worksheet, number, defn) {
         this._worksheet = worksheet;
@@ -20,6 +22,9 @@ class Column {
     get worksheet() {
         return this._worksheet;
     }
+    /**
+     * Column letter key
+     */
     get letter() {
         return colCache.n2l(this._number);
     }
@@ -68,6 +73,9 @@ class Column {
         }
         return [];
     }
+    /**
+     * Can be a string to set one row high header or an array to set multi-row high header
+     */
     get header() {
         return this._header;
     }
@@ -82,6 +90,9 @@ class Column {
             this._header = undefined;
         }
     }
+    /**
+     * The name of the properties associated with this column in each row
+     */
     get key() {
         return this._key;
     }
@@ -95,18 +106,27 @@ class Column {
             this._worksheet.setColumnKey(this._key, this);
         }
     }
+    /**
+     * Hides the column
+     */
     get hidden() {
         return !!this._hidden;
     }
     set hidden(value) {
         this._hidden = value;
     }
+    /**
+     * Set an outline level for columns
+     */
     get outlineLevel() {
         return this._outlineLevel || 0;
     }
     set outlineLevel(value) {
         this._outlineLevel = value;
     }
+    /**
+     * Indicate the collapsed state based on outlineLevel
+     */
     get collapsed() {
         return !!(this._outlineLevel && this._outlineLevel >= this._worksheet.properties.outlineLevelCol);
     }
@@ -148,16 +168,25 @@ class Column {
     get headerCount() {
         return this.headers.length;
     }
-    eachCell(options, iteratee) {
+    eachCell(optionsOrCallback, maybeCallback) {
         const colNumber = this.number;
-        if (!iteratee) {
-            iteratee = options;
+        let options;
+        let callback;
+        if (typeof optionsOrCallback === "function") {
             options = {};
+            callback = optionsOrCallback;
+        }
+        else {
+            options = optionsOrCallback;
+            callback = maybeCallback;
         }
         this._worksheet.eachRow(options, (row, rowNumber) => {
-            iteratee(row.getCell(colNumber), rowNumber);
+            callback(row.getCell(colNumber), rowNumber);
         });
     }
+    /**
+     * The cell values in the column
+     */
     get values() {
         const v = [];
         this.eachCell((cell, rowNumber) => {

package/dist/esm/doc/row.js

@@ -9,19 +9,29 @@ class Row {
         this.style = {};
         this.outlineLevel = 0;
     }
-    // return the row number
+    /**
+     * The row number
+     */
     get number() {
         return this._number;
     }
+    /**
+     * The worksheet that contains this row
+     */
     get worksheet() {
         return this._worksheet;
     }
-    // Inform Streaming Writer that this row (and all rows before it) are complete
-    // and ready to write. Has no effect on Worksheet document
+    /**
+     * Commit a completed row to stream.
+     * Inform Streaming Writer that this row (and all rows before it) are complete
+     * and ready to write. Has no effect on Worksheet document.
+     */
     commit() {
         this._worksheet._commitRow(this);
     }
-    // helps GC by breaking cyclic references
+    /**
+     * Helps GC by breaking cyclic references
+     */
     destroy() {
         delete this._worksheet;
         delete this._cells;
@@ -40,7 +50,9 @@ class Row {
         }
         return cell;
     }
-    // get cell by key, letter or column number
+    /**
+     * Get cell by number, column letter or column key
+     */
     getCell(col) {
         let colNum;
         if (typeof col === "string") {
@@ -63,7 +75,11 @@ class Row {
                 col: colNum
             }));
     }
-    // remove cell(s) and shift all higher cells down by count
+    /**
+     * Cut one or more cells (cells to the right are shifted left)
+     *
+     * Note: this operation will not affect other rows
+     */
     splice(start, count, ...inserts) {
         const nKeep = start + count;
         const nExpand = inserts.length - count;
@@ -112,26 +128,26 @@ class Row {
             cDst.comment = undefined;
         }
     }
-    eachCell(optionsOrIteratee, maybeIteratee) {
+    eachCell(optOrCallback, maybeCallback) {
         let options = null;
-        let iteratee;
-        if (typeof optionsOrIteratee === "function") {
-            iteratee = optionsOrIteratee;
+        let callback;
+        if (typeof optOrCallback === "function") {
+            callback = optOrCallback;
         }
         else {
-            options = optionsOrIteratee;
-            iteratee = maybeIteratee;
+            options = optOrCallback;
+            callback = maybeCallback;
         }
         if (options && options.includeEmpty) {
             const n = this._cells.length;
             for (let i = 1; i <= n; i++) {
-                iteratee(this.getCell(i), i);
+                callback(this.getCell(i), i);
             }
         }
         else {
             this._cells.forEach((cell, index) => {
                 if (cell && cell.type !== Enums.ValueType.Null) {
-                    iteratee(cell, index + 1);
+                    callback(cell, index + 1);
                 }
             });
         }
@@ -152,7 +168,9 @@ class Row {
         }
         ws.rowBreaks.push(pb);
     }
-    // return a sparse array of cell values
+    /**
+     * Get a row as a sparse array
+     */
     get values() {
         const values = [];
         this._cells.forEach(cell => {
@@ -162,7 +180,9 @@ class Row {
         });
         return values;
     }
-    // set the values by contiguous or sparse array, or by key'd object literal
+    /**
+     * Set the values by contiguous or sparse array, or by key'd object literal
+     */
     set values(value) {
         // this operation is not additive - any prior cells are removed
         this._cells = [];
@@ -198,13 +218,21 @@ class Row {
             });
         }
     }
-    // returns true if the row includes at least one cell with a value
+    /**
+     * Returns true if the row includes at least one cell with a value
+     */
     get hasValues() {
         return this._cells.some(cell => cell && cell.type !== Enums.ValueType.Null);
     }
+    /**
+     * Number of cells including empty ones
+     */
     get cellCount() {
         return this._cells.length;
     }
+    /**
+     * Number of non-empty cells
+     */
     get actualCellCount() {
         let count = 0;
         this.eachCell(() => {
@@ -212,7 +240,9 @@ class Row {
         });
         return count;
     }
-    // get the min and max column number for the non-null cells in this row or null
+    /**
+     * Get the min and max column number for the non-null cells in this row or null
+     */
     get dimensions() {
         let min = 0;
         let max = 0;