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

package/dist/browser/excelts.iife.js

@@ -1,5 +1,5 @@
 /*!
- * @cj-tech-master/excelts v1.4.5-canary.20251212064440.3eb099f
+ * @cj-tech-master/excelts v1.4.5-canary.20251212160853.7621827
  * TypeScript Excel Workbook Manager - Read and Write xlsx and csv Files.
  * (c) 2025 cjnoname
  * Released under the MIT License
@@ -1559,15 +1559,29 @@ var ExcelTS = (function(exports) {
 			this.style = {};
 			this.outlineLevel = 0;
 		}
+		/**
+		* The row number
+		*/
 		get number() {
 			return this._number;
 		}
+		/**
+		* The worksheet that contains this row
+		*/
 		get worksheet() {
 			return this._worksheet;
 		}
+		/**
+		* 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
+		*/
 		destroy() {
 			delete this._worksheet;
 			delete this._cells;
@@ -1585,6 +1599,9 @@ var ExcelTS = (function(exports) {
 			}
 			return cell;
 		}
+		/**
+		* Get cell by number, column letter or column key
+		*/
 		getCell(col) {
 			let colNum;
 			if (typeof col === "string") {
@@ -1598,6 +1615,11 @@ var ExcelTS = (function(exports) {
 				col: colNum
 			});
 		}
+		/**
+		* 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;
@@ -1635,19 +1657,19 @@ var ExcelTS = (function(exports) {
 				cDst.comment = void 0;
 			}
 		}
-		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 = 1; i$1 <= n; i$1++) iteratee(this.getCell(i$1), i$1);
+				for (let i$1 = 1; i$1 <= n; i$1++) callback(this.getCell(i$1), i$1);
 			} else this._cells.forEach((cell, index) => {
-				if (cell && cell.type !== Enums.ValueType.Null) iteratee(cell, index + 1);
+				if (cell && cell.type !== Enums.ValueType.Null) callback(cell, index + 1);
 			});
 		}
 		addPageBreak(lft, rght) {
@@ -1662,6 +1684,9 @@ var ExcelTS = (function(exports) {
 			if (left) pb.min = left;
 			ws.rowBreaks.push(pb);
 		}
+		/**
+		* Get a row as a sparse array
+		*/
 		get values() {
 			const values = [];
 			this._cells.forEach((cell) => {
@@ -1669,6 +1694,9 @@ var ExcelTS = (function(exports) {
 			});
 			return values;
 		}
+		/**
+		* Set the values by contiguous or sparse array, or by key'd object literal
+		*/
 		set values(value) {
 			this._cells = [];
 			if (!value) {} else if (value instanceof Array) {
@@ -1689,12 +1717,21 @@ var ExcelTS = (function(exports) {
 				}).value = value[key];
 			});
 		}
+		/**
+		* 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(() => {
@@ -1702,6 +1739,9 @@ var ExcelTS = (function(exports) {
 			});
 			return count;
 		}
+		/**
+		* Get the min and max column number for the non-null cells in this row or null
+		*/
 		get dimensions() {
 			let min = 0;
 			let max$1 = 0;
@@ -1837,6 +1877,11 @@ var ExcelTS = (function(exports) {
 //#endregion
 //#region src/doc/column.ts
 	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
+	*/
 	var Column = class Column {
 		constructor(worksheet, number, defn) {
 			this._worksheet = worksheet;
@@ -1849,6 +1894,9 @@ var ExcelTS = (function(exports) {
 		get worksheet() {
 			return this._worksheet;
 		}
+		/**
+		* Column letter key
+		*/
 		get letter() {
 			return colCache.n2l(this._number);
 		}
@@ -1887,6 +1935,9 @@ var ExcelTS = (function(exports) {
 			if (this._header !== void 0) return [this._header];
 			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;
 		}
@@ -1898,6 +1949,9 @@ var ExcelTS = (function(exports) {
 				});
 			} else this._header = void 0;
 		}
+		/**
+		* The name of the properties associated with this column in each row
+		*/
 		get key() {
 			return this._key;
 		}
@@ -1906,18 +1960,27 @@ var ExcelTS = (function(exports) {
 			this._key = value;
 			if (value) 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);
 		}
@@ -1945,16 +2008,24 @@ var ExcelTS = (function(exports) {
 		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) => {
@@ -26576,12 +26647,21 @@ var ExcelTS = (function(exports) {
 			if (this._workbook.worksheets.find((ws) => ws && ws.name.toLowerCase() === name.toLowerCase())) throw new Error(`Worksheet name already exists: ${name}`);
 			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
+		*/
 		destroy() {
 			this._workbook.removeWorksheetEx(this);
 		}
+		/**
+		* Get the bounding range of the cells in this worksheet
+		*/
 		get dimensions() {
 			const dimensions = new Range();
 			this._rows.forEach((row) => {
@@ -26592,9 +26672,18 @@ var ExcelTS = (function(exports) {
 			});
 			return dimensions;
 		}
+		/**
+		* Get the current columns array
+		*/
 		get columns() {
 			return this._columns;
 		}
+		/**
+		* 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) {
 			this._headerRowCount = value.reduce((pv, cv) => {
 				const headerCount = Array.isArray(cv.header) ? cv.header.length : cv.header ? 1 : 0;
@@ -26620,6 +26709,9 @@ var ExcelTS = (function(exports) {
 		eachColumnKey(f) {
 			Object.keys(this._keys).forEach((key) => f(this._keys[key], key));
 		}
+		/**
+		* Access an individual column by key, letter and 1-based column number
+		*/
 		getColumn(c) {
 			let colNum;
 			if (typeof c === "string") {
@@ -26634,6 +26726,17 @@ var ExcelTS = (function(exports) {
 			}
 			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 nRows = this._rows.length;
 			if (inserts.length > 0) for (let i$1 = 0; i$1 < nRows; i$1++) {
@@ -26651,9 +26754,15 @@ var ExcelTS = (function(exports) {
 			for (let i$1 = start; i$1 < start + inserts.length; i$1++) this.getColumn(i$1).defn = void 0;
 			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) => {
@@ -26661,6 +26770,9 @@ var ExcelTS = (function(exports) {
 			});
 			return maxCount;
 		}
+		/**
+		* A count of the number of columns that have values
+		*/
 		get actualColumnCount() {
 			const counts = [];
 			let count = 0;
@@ -26684,18 +26796,38 @@ var ExcelTS = (function(exports) {
 		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];
 		}
+		/**
+		* 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];
 		}
+		/**
+		* 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() {
 			let count = 0;
 			this.eachRow(() => {
@@ -26703,17 +26835,27 @@ var ExcelTS = (function(exports) {
 			});
 			return count;
 		}
+		/**
+		* Get or create row by 1-based index
+		*/
 		getRow(r) {
 			let row = this._rows[r - 1];
 			if (!row) row = this._rows[r - 1] = new Row(this, r);
 			return row;
 		}
+		/**
+		* Get or create rows by 1-based index
+		*/
 		getRows(start, length) {
 			if (length < 1) return;
 			const rows = [];
 			for (let i$1 = start; i$1 < start + length; i$1++) rows.push(this.getRow(i$1));
 			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);
@@ -26721,6 +26863,9 @@ var ExcelTS = (function(exports) {
 			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) => {
@@ -26728,11 +26873,19 @@ var ExcelTS = (function(exports) {
 			});
 			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") {
@@ -26754,6 +26907,9 @@ var ExcelTS = (function(exports) {
 			});
 			rDst.height = rSrc.height;
 		}
+		/**
+		* Duplicate rows and insert new rows
+		*/
 		duplicateRow(rowNum, count, insert = false) {
 			const rSrc = this._rows[rowNum - 1];
 			const inserts = Array.from({ length: count }).fill(rSrc.values);
@@ -26767,6 +26923,12 @@ var ExcelTS = (function(exports) {
 				});
 			}
 		}
+		/**
+		* 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) {
 			const nKeep = start + count;
 			const nInserts = inserts.length;
@@ -26814,18 +26976,24 @@ var ExcelTS = (function(exports) {
 			}
 			this.workbook.definedNames.spliceRows(this.name, start, count, nInserts);
 		}
-		eachRow(options, iteratee) {
-			if (!iteratee) {
-				iteratee = options;
-				options = void 0;
+		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 = 1; i$1 <= n; i$1++) iteratee(this.getRow(i$1), i$1);
+				for (let i$1 = 1; i$1 <= n; i$1++) callback(this.getRow(i$1), i$1);
 			} else this._rows.forEach((row) => {
-				if (row && row.hasValues) iteratee(row, row.number);
+				if (row && row.hasValues) callback(row, row.number);
 			});
 		}
+		/**
+		* Return all rows as sparse array
+		*/
 		getSheetValues() {
 			const rows = [];
 			this._rows.forEach((row) => {
@@ -26833,15 +27001,30 @@ var ExcelTS = (function(exports) {
 			});
 			return rows;
 		}
+		/**
+		* Returns the cell at [r,c] or address given by r. If not found, return undefined
+		*/
 		findCell(r, c) {
 			const address = colCache.getAddress(r, c);
 			const row = this._rows[address.row - 1];
 			return row ? row.findCell(address.col) : void 0;
 		}
+		/**
+		* Get or create cell at [r,c] or address given by r
+		*/
 		getCell(r, c) {
 			const address = colCache.getAddress(r, c);
 			return this.getRow(address.row).getCellEx(address);
 		}
+		/**
+		* 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(cells);
 			this._mergeCellsInternal(dimensions);
@@ -26868,6 +27051,11 @@ var ExcelTS = (function(exports) {
 		get hasMerges() {
 			return Object.values(this._merges).some(Boolean);
 		}
+		/**
+		* 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(cells);
 			for (let i$1 = dimensions.top; i$1 <= dimensions.bottom; i$1++) for (let j = dimensions.left; j <= dimensions.right; j++) {
@@ -26903,6 +27091,10 @@ var ExcelTS = (function(exports) {
 				result: getResult(r, c)
 			} : getResult(r, c);
 		}
+		/**
+		* Using the image id from `Workbook.addImage`,
+		* embed an image within the worksheet to cover a range
+		*/
 		addImage(imageId, range$1) {
 			const model = {
 				type: "image",
@@ -26914,6 +27106,9 @@ var ExcelTS = (function(exports) {
 		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",
@@ -26925,6 +27120,9 @@ var ExcelTS = (function(exports) {
 			const image = this._media.find((m) => m.type === "background");
 			return image && image.imageId;
 		}
+		/**
+		* Protect the worksheet with optional password and options
+		*/
 		protect(password, options) {
 			return new Promise((resolve) => {
 				this.sheetProtection = { sheet: true };
@@ -26945,17 +27143,29 @@ var ExcelTS = (function(exports) {
 		unprotect() {
 			this.sheetProtection = null;
 		}
+		/**
+		* Add a new table and return a reference to it
+		*/
 		addTable(model) {
 			const table = new 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);
 		}
@@ -26967,9 +27177,15 @@ Please leave feedback at https://github.com/excelts/excelts/discussions/2575`);
 			this.workbook.pivotTables.push(pivotTable);
 			return pivotTable;
 		}
+		/**
+		* 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);
 			else if (filter instanceof Function) this.conditionalFormattings = this.conditionalFormattings.filter(filter);
@@ -50309,10 +50525,16 @@ ${XMLNS_NAMESPACE}.`);
 			this.pivotTables = [];
 			this._definedNames = new DefinedNames();
 		}
+		/**
+		* xlsx file format operations
+		*/
 		get xlsx() {
 			if (!this._xlsx) this._xlsx = new XLSX(this);
 			return this._xlsx;
 		}
+		/**
+		* csv file format operations
+		*/
 		get csv() {
 			if (!this._csv) this._csv = new CSV(this);
 			return this._csv;
@@ -50321,6 +50543,9 @@ ${XMLNS_NAMESPACE}.`);
 			for (let i$1 = 1; i$1 < this._worksheets.length; i$1++) if (!this._worksheets[i$1]) return i$1;
 			return this._worksheets.length || 1;
 		}
+		/**
+		* Add a new worksheet and return a reference to it
+		*/
 		addWorksheet(name, options) {
 			const id = this.nextId;
 			const lastOrderNo = this._worksheets.reduce((acc, ws) => (ws && ws.orderNo) > acc ? ws.orderNo : acc, 0);
@@ -50341,17 +50566,28 @@ ${XMLNS_NAMESPACE}.`);
 			const worksheet = this.getWorksheet(id);
 			if (worksheet) worksheet.destroy();
 		}
+		/**
+		* Fetch sheet by name or id
+		*/
 		getWorksheet(id) {
 			if (id === void 0) return this._worksheets.find(Boolean);
 			if (typeof id === "number") return this._worksheets[id];
 			if (typeof id === "string") return this._worksheets.find((worksheet) => worksheet && worksheet.name === id);
 		}
+		/**
+		* Return a clone of worksheets in order
+		*/
 		get worksheets() {
 			return this._worksheets.slice(1).sort((a, b) => a.orderNo - b.orderNo).filter(Boolean);
 		}
-		eachSheet(iteratee) {
+		/**
+		* Iterate over all sheets.
+		*
+		* Note: `workbook.worksheets.forEach` will still work but this is better.
+		*/
+		eachSheet(callback) {
 			this.worksheets.forEach((sheet) => {
-				iteratee(sheet, sheet.id);
+				callback(sheet, sheet.id);
 			});
 		}
 		get definedNames() {
@@ -50360,6 +50596,9 @@ ${XMLNS_NAMESPACE}.`);
 		clearThemes() {
 			this._themes = void 0;
 		}
+		/**
+		* Add Image to Workbook and return the id
+		*/
 		addImage(image) {
 			const id = this.media.length;
 			this.media.push({