@xlvane/compat 1.0.1 → 1.1.1

package/README.md

@@ -56,9 +56,9 @@ In CommonJS, `const ExcelJS = require('exceljs');` gives the same object; call `
 The full list, with the exceljs source of each behaviour, is in [docs/exceljs-compat.md](https://github.com/DevXord/xlvane/blob/main/docs/exceljs-compat.md) (also in `node_modules/xlvane/docs/exceljs-compat.md` after installing). The ones most likely to matter:
 
 - **Not offered:** row and column operations on a streamed worksheet (`insertRow(s)`, `spliceRows`, `duplicateRow`, `spliceColumns`; exceljs's streaming worksheet does not have them either) throw an `XlvError` with code `XLV_E_NOT_SUPPORTED` and the name of the method. Deep imports of exceljs internals (`exceljs/lib/...`) do not resolve; `exceljs/dist/es5` and the `exceljs/dist/exceljs*.js` files do. Nothing is dropped silently.
-- **CSV:** text that starts with `=`, `+`, `-`, `@`, a tab, CR or LF is written with a leading `'`, so spreadsheet applications do not run it as a formula. `formulaInjection: "off"` writes it unchanged, as exceljs does.
-- **Sheet ids:** the file gets `sheetId` 1, 2, 3… in sheet order, and a loaded workbook numbers its sheets 1, 2, 3… in file order. After removing a sheet, `getWorksheet(id)` can give another sheet than with exceljs; look sheets up by name.
-- **Views:** only the first view of a worksheet is written; a split view is written without its `topLeftCell`.
+- **CSV:** text that starts with `=`, `+`, `-`, `@`, a tab, CR, LF or another control character, or with a full-width or small form of these signs, is written with a leading `'`, so spreadsheet applications do not run it as a formula. `formulaInjection: "off"` writes it unchanged, as exceljs does.
+- **Sheet ids:** `worksheet.id` is written as `sheetId` and kept on loading, as in exceljs; an id outside 1 to 65534 is written as the lowest unused one, and the streaming `WorkbookReader` numbers worksheets 1, 2, 3… in file order.
+- **Views:** only the first view of a worksheet is written; a frozen view always gets the cell right of and below the panes as `topLeftCell`.
 - **Notes:** `protection.locked` and `lockText` read back as `'True'`/`'False'`, the values Excel writes.
 - **Module object:** it is frozen, so adding or replacing its properties (monkey-patching) has no effect.
 - **Streaming writer speed:** `stream.xlsx.WorkbookWriter` compresses in JavaScript (fflate) and took about twice as long as exceljs, which uses Node.js zlib (300 000 rows: 6.1 s against 2.8 s).
@@ -66,6 +66,7 @@ The full list, with the exceljs source of each behaviour, is in [docs/exceljs-co
 
 ## Links
 
+- Website: [xlvane.github.io](https://xlvane.github.io)
 - Changes in each version: [CHANGELOG.md](https://github.com/DevXord/xlvane/blob/main/CHANGELOG.md)
 - Bugs and questions: [GitHub issues](https://github.com/DevXord/xlvane/issues)
 - Reporting a vulnerability: [SECURITY.md](https://github.com/DevXord/xlvane/blob/main/SECURITY.md)

package/dist/index.d.ts

@@ -295,6 +295,8 @@ export declare class Workbook {
   get nextId(): number;
   /** Adds a worksheet. Names follow exceljs rules (31 characters at most; longer names are cut). */
   addWorksheet(name?: string, options?: WorksheetOptions): Worksheet;
+  /** @internal Adds a worksheet with a given id (a loaded file's sheetId, a model's id; D-F03). */
+  _addWorksheetWithId(id: number, name?: string, options?: WorksheetOptions): Worksheet;
   removeWorksheet(id: number | string): void;
   /** Removes a worksheet by id or name, as `removeWorksheet` (lib/doc/workbook.js L77). */
   removeWorksheetEx(worksheet: Worksheet): void;
@@ -2698,6 +2700,20 @@ export declare class Column {
   get protection(): Partial<Protection> | undefined;
   set protection(v: Partial<Protection> | undefined);
 }
+/** A merged range of a worksheet. */
+type MergeRange = {
+  top: number;
+  left: number;
+  bottom: number;
+  right: number;
+};
+/** The merged ranges of a worksheet by master address, with a counter of changes (D-H01). */
+declare class MergeMap extends Map<string, MergeRange> {
+  version: number;
+  override set(key: string, value: MergeRange): this;
+  override delete(key: string): boolean;
+  override clear(): void;
+}
 /**
  * A worksheet, as exceljs `Worksheet` (lib/doc/worksheet.js).
  *
@@ -2759,12 +2775,10 @@ export declare class Worksheet {
   /** @internal */
   _columns: Column[];
   /** @internal */
-  _merges: Map<string, {
-    top: number;
-    left: number;
-    bottom: number;
-    right: number;
-  }>;
+  _merges: MergeMap;
+  /** The cells covered by `_merges` (row × 16 385 + column), valid while `_mergedVersion` equals `_merges.version`. */
+  private _mergedCells;
+  private _mergedVersion;
   private readonly _keys;
   private _name;
   /** @internal Use `workbook.addWorksheet()`. */
@@ -2927,6 +2941,8 @@ export declare class Worksheet {
   mergeCellsWithoutStyle(...args: unknown[]): void;
   private _mergeKeepStyle;
   mergeCells(...args: unknown[]): void;
+  /** The index of merged cells, rebuilt from `_merges` after any other change to it. */
+  private _mergedIndex;
   unMergeCells(...args: unknown[]): void;
   get hasMerges(): boolean;
   /** Adds conditional formatting for a range (exceljs `addConditionalFormatting`). */

package/dist/index.js

@@ -1,4 +1,4 @@
-import { XlvError, adjustFormula, adjustRange, createWorkbook, hashPassword, imageFormat, openWorkbookStream, readWorkbook, shiftFormula, writeWorkbook, writeWorkbookStream } from "xlvane";
+import { DEFAULT_READ_LIMITS, XlvError, adjustFormula, adjustRange, createWorkbook, hashPassword, imageFormat, openWorkbookStream, readWorkbook, shiftFormula, writeWorkbook, writeWorkbookStream } from "xlvane";
 // src/media.ts
 const MAX_COLS = 16384;
 const MAX_ROWS = 1048576;
@@ -1228,9 +1228,10 @@ function noteBoxOut(box) {
 * The first exceljs view and the tab colour (X4-11, X4-12). xlvane writes one view: frozen panes
 * (`xSplit`/`ySplit` in columns and rows) or a split window (`xSplit`/`ySplit` in 1/20 point, as
 * exceljs), plus `zoomScale`, `showGridLines`, `showRowColHeaders`, `rightToLeft` and `style`.
-* `activeCell` is written for every view; `topLeftCell` only for a normal view (a split view's
-* exceljs `topLeftCell` is `pane@topLeftCell`, which the core does not write); `activePane`
-* follows from the panes.
+* `activeCell` is written for every view; `topLeftCell` for a normal view as
+* `sheetView@topLeftCell` and for a split view as `pane@topLeftCell`, as exceljs writes them
+* (sheet-view-xform.js L72-85; D-F02); a frozen view's `topLeftCell` follows from the panes;
+* `activePane` follows from the panes.
 */
 function layoutIn(ws) {
 	const v = ws.views[0];
@@ -1251,10 +1252,14 @@ function layoutIn(ws) {
 			rows: v.ySplit ?? 0,
 			cols: v.xSplit ?? 0
 		};
-		else if (v.state === "split" && ((v.xSplit ?? 0) > 0 || (v.ySplit ?? 0) > 0)) view.split = {
-			x: (v.xSplit ?? 0) / 20,
-			y: (v.ySplit ?? 0) / 20
-		};
+		else if (v.state === "split" && ((v.xSplit ?? 0) > 0 || (v.ySplit ?? 0) > 0)) {
+			const corner = typeof v["topLeftCell"] === "string" && v["topLeftCell"] !== "" ? { topLeftCell: v["topLeftCell"] } : {};
+			view.split = {
+				x: (v.xSplit ?? 0) / 20,
+				y: (v.ySplit ?? 0) / 20,
+				...corner
+			};
+		}
 	}
 	let tab = ws.properties["tabColor"];
 	if (tab && typeof tab.argb === "string" && /^[0-9A-Fa-f]{7}$/.test(tab.argb)) tab = {
@@ -1356,7 +1361,10 @@ function toNewWorkbook(sheets, date1904, meta = {}) {
 	if (meta.views && meta.views.length > 0) book.views(bookViewsIn(meta.views));
 	if (meta.calcProperties?.["fullCalcOnLoad"]) book.calculation({ fullCalcOnLoad: true });
 	for (const ws of sheets) at(ws.name, void 0, () => {
-		const sheet = book.addSheet(ws.name, { state: ws.state });
+		const sheet = book.addSheet(ws.name, {
+			state: ws.state,
+			...sheetIdOf(ws.id)
+		});
 		const useStyles = meta.useStyles !== false;
 		const sharedRanges = sharedFormulaRanges(ws);
 		const props = sheetPropertiesIn(ws.properties);
@@ -1487,8 +1495,9 @@ function fontOut(f) {
 /**
 * An exceljs view from the view read by xlvane, shaped as exceljs reads one (sheet-view-xform.js
 * L145–192; X4-11): a missing `zoomScaleNormal` reads as 100; a frozen view gets the default
-* `topLeftCell`; a split view gets `xSplit`/`ySplit` in 1/20 point and the active pane xlvane
-* writes; a normal view has no `topLeftCell`, as in exceljs.
+* `topLeftCell`; a split view gets `xSplit`/`ySplit` in 1/20 point, `pane@topLeftCell` as
+* `topLeftCell` (sheet-view-xform.js L118-124) and the active pane xlvane writes; a normal view
+* has no `topLeftCell`, as in exceljs.
 */
 function viewOut(view, freeze) {
 	const common = {
@@ -1516,14 +1525,14 @@ function viewOut(view, freeze) {
 	}
 	const active = view.activeCell !== null ? { activeCell: view.activeCell } : {};
 	if (view.split) {
-		const { x, y } = view.split;
+		const { x, y, topLeftCell } = view.split;
 		const activePane = x > 0 && y > 0 ? "bottomRight" : y > 0 ? "bottomLeft" : "topRight";
 		return {
 			...common,
 			state: "split",
 			xSplit: Math.round(x * 20),
 			ySplit: Math.round(y * 20),
-			topLeftCell: void 0,
+			topLeftCell,
 			activePane,
 			...active,
 			...style
@@ -1665,6 +1674,10 @@ function styleOut(s, numFmt) {
 function readBytes(bytes) {
 	return readWorkbook(bytes);
 }
+/** `{ sheetId }` for a worksheet id that Office accepts (1 to 65534, W2-20), otherwise nothing (D-F03). */
+function sheetIdOf(id) {
+	return Number.isInteger(id) && id >= 1 && id <= 65534 ? { sheetId: id } : {};
+}
 // src/sheet-rules.ts
 const MAX_ROW = 1048576;
 const MAX_COL = 16384;
@@ -3615,6 +3628,22 @@ function parseRangeArgs(args) {
 		right: Math.max(s.col, e.col)
 	};
 }
+/** The merged ranges of a worksheet by master address, with a counter of changes (D-H01). */
+var MergeMap = class extends Map {
+	version = 0;
+	set(key, value) {
+		this.version++;
+		return super.set(key, value);
+	}
+	delete(key) {
+		this.version++;
+		return super.delete(key);
+	}
+	clear() {
+		this.version++;
+		super.clear();
+	}
+};
 /**
 * A worksheet, as exceljs `Worksheet` (lib/doc/worksheet.js).
 *
@@ -3660,7 +3689,10 @@ var Worksheet = class {
 	/** @internal */
 	_columns = [];
 	/** @internal */
-	_merges = /* @__PURE__ */ new Map();
+	_merges = new MergeMap();
+	/** The cells covered by `_merges` (row × 16 385 + column), valid while `_mergedVersion` equals `_merges.version`. */
+	_mergedCells = /* @__PURE__ */ new Set();
+	_mergedVersion = -1;
 	_keys = /* @__PURE__ */ new Map();
 	_name = "";
 	/** @internal Use `workbook.addWorksheet()`. */
@@ -4365,7 +4397,8 @@ var Worksheet = class {
 	_mergeKeepStyle = false;
 	mergeCells(...args) {
 		const range = parseRangeArgs(args);
-		for (const m of this._merges.values()) if (range.top <= m.bottom && m.top <= range.bottom && range.left <= m.right && m.left <= range.right) throw new Error("Cannot merge already merged cells");
+		const merged = this._mergedIndex();
+		for (let r = range.top; r <= range.bottom; r++) for (let c = range.left; c <= range.right; c++) if (merged.has(r * 16385 + c)) throw new Error("Cannot merge already merged cells");
 		const master = this.getCell(range.top, range.left);
 		for (let r = range.top; r <= range.bottom; r++) for (let c = range.left; c <= range.right; c++) {
 			if (r === range.top && c === range.left) continue;
@@ -4375,6 +4408,17 @@ var Worksheet = class {
 		}
 		master._mergeCount++;
 		this._merges.set(`${columnLetter(range.left)}${String(range.top)}`, range);
+		for (let r = range.top; r <= range.bottom; r++) for (let c = range.left; c <= range.right; c++) merged.add(r * 16385 + c);
+		this._mergedVersion = this._merges.version;
+	}
+	/** The index of merged cells, rebuilt from `_merges` after any other change to it. */
+	_mergedIndex() {
+		if (this._mergedVersion !== this._merges.version) {
+			this._mergedCells = /* @__PURE__ */ new Set();
+			for (const m of this._merges.values()) for (let r = m.top; r <= m.bottom; r++) for (let c = m.left; c <= m.right; c++) this._mergedCells.add(r * 16385 + c);
+			this._mergedVersion = this._merges.version;
+		}
+		return this._mergedCells;
 	}
 	unMergeCells(...args) {
 		const range = parseRangeArgs(args);
@@ -4562,7 +4606,11 @@ const INJECTION_START = /* @__PURE__ */ new Set([
 	"＝",
 	"＋",
 	"－",
-	"＠"
+	"＠",
+	"﹦",
+	"﹢",
+	"﹣",
+	"﹫"
 ]);
 function invalid(name, message, hint) {
 	return new XlvError("XLV_E_INVALID_OPTION", message, {
@@ -5019,7 +5067,7 @@ function worksheetCsv(sheet, options) {
 	const escape = (out) => {
 		if (injection !== "escape" || typeof out !== "string") return [out, false];
 		const first = out.replace(/\0/g, "")[0];
-		return first !== void 0 && INJECTION_START.has(first) ? [`'${out}`, f.quote !== ""] : [out, false];
+		return first !== void 0 && (INJECTION_START.has(first) || first.charCodeAt(0) < 32) ? [`'${out}`, f.quote !== ""] : [out, false];
 	};
 	if (f.headers) lines.push(f.headers.map((h, i) => {
 		const [out, force] = escape(h);
@@ -5844,7 +5892,10 @@ var Workbook = class {
 	}
 	/** Adds a worksheet. Names follow exceljs rules (31 characters at most; longer names are cut). */
 	addWorksheet(name, options) {
-		const id = this.nextId;
+		return this._addWorksheetWithId(this.nextId, name, options);
+	}
+	/** @internal Adds a worksheet with a given id (a loaded file's sheetId, a model's id; D-F03). */
+	_addWorksheetWithId(id, name, options) {
 		const sheet = new Worksheet(this, id, name, options);
 		sheet.orderNo = this._sheets.reduce((acc, ws) => ws?.orderNo !== void 0 && ws.orderNo > acc ? ws.orderNo : acc, 0) + 1;
 		this._sheets[id] = sheet;
@@ -5916,8 +5967,10 @@ var Workbook = class {
 		this.views = Array.isArray(value["views"]) ? [...value["views"]] : [];
 		this._media = Array.isArray(value["media"]) ? [...value["media"]] : [];
 		for (const ws of this.worksheets) this.removeWorksheet(ws.id);
-		for (const m of Array.isArray(value["worksheets"]) ? value["worksheets"] : []) {
-			const ws = this.addWorksheet(String(m["name"] ?? ""), { state: m["state"] ?? "visible" });
+		const models = Array.isArray(value["worksheets"]) ? value["worksheets"] : [];
+		const ids = freeIds(models.map((m) => m["id"]));
+		for (const [i, m] of models.entries()) {
+			const ws = this._addWorksheetWithId(ids[i] ?? this.nextId, String(m["name"] ?? ""), { state: m["state"] ?? "visible" });
 			ws.model = m;
 		}
 		this._definedNames.model = Array.isArray(value["definedNames"]) ? value["definedNames"] : [];
@@ -5967,6 +6020,24 @@ var Workbook = class {
 	_fill(read, options = {}) {
 		const ignore = new Set(options.ignoreNodes ?? []);
 		const use = (node) => !ignore.has(node);
+		let cellsRead = 0;
+		for (const s of read.sheets) cellsRead += s.cellCount;
+		const budget = Math.max(DEFAULT_READ_LIMITS.maxCells, 16 * cellsRead);
+		let spent = 0;
+		const spend = (positions, what, sheet) => {
+			spent += positions;
+			if (spent <= budget) return;
+			throw new XlvError("XLV_E_LIMIT_EXCEEDED", `${what} of worksheet "${sheet}" would create more than ${String(budget)} cells or columns for ${String(cellsRead)} cells in the file.`, {
+				location: { sheet },
+				hint: "The file declares ranges far larger than its data. Load it with ignoreNodes for that element (for example ignoreNodes: [\"mergeCells\"]), or read it with xlvane's readWorkbook, which does not create these objects.",
+				details: {
+					limit: "maxCells",
+					value: budget
+				}
+			});
+		};
+		const rowBudget = Math.max(67108864, 16 * cellsRead);
+		let rowsLooked = 0;
 		for (const s of read.sheets) {
 			if (s.kind !== "worksheet" || options.maxRows === void 0 && options.maxCols === void 0 || !use("sheetData")) continue;
 			const perRow = /* @__PURE__ */ new Map();
@@ -6030,12 +6101,14 @@ var Workbook = class {
 			name: d.name,
 			ranges: extractRanges(d.refersTo)
 		}));
+		const ids = freeIds(read.sheets.map((s) => s.kind === "worksheet" ? s.sheetId : void 0));
 		for (const [position, s] of read.sheets.entries()) {
 			if (s.kind !== "worksheet") continue;
-			const ws = this.addWorksheet(s.name, { state: s.state });
+			const ws = this._addWorksheetWithId(ids[position] ?? this.nextId, s.name, { state: s.state });
 			ws.orderNo = position;
 			for (const c of use("cols") ? s.columns : []) {
 				const last = Math.min(c.max, 16384);
+				spend(Math.max(0, last - c.min + 1), "The column definitions", s.name);
 				for (let n = c.min; n <= last; n++) {
 					const column = ws.getColumn(n);
 					if (c.width !== null) column.width = c.width;
@@ -6089,6 +6162,15 @@ var Workbook = class {
 			}
 			const dim = /(\d+)$/.exec(s.dimension ?? "");
 			lastRow = use("sheetData") ? Math.min(Math.max(lastRow, dim ? Number(dim[1]) : 0), 1048576) : 0;
+			rowsLooked += lastRow;
+			if (rowsLooked > rowBudget) throw new XlvError("XLV_E_LIMIT_EXCEEDED", `The rows of worksheet "${s.name}" up to its dimension or last cell would bring the rows looked at for their settings past ${String(rowBudget)} for ${String(cellsRead)} cells in the file.`, {
+				location: { sheet: s.name },
+				hint: "The sheets declare far more rows than they hold. Load the file with ignoreNodes: [\"sheetData\"] to skip cells and rows, or read it with xlvane's readWorkbook.",
+				details: {
+					limit: "maxCells",
+					value: rowBudget
+				}
+			});
 			for (let r = 1; r <= lastRow; r++) {
 				const info = s.rowInfo(r);
 				if (!info) continue;
@@ -6098,7 +6180,11 @@ var Workbook = class {
 				if (info.outlineLevel) row.outlineLevel = info.outlineLevel;
 			}
 			for (const note of s.notes) ws.getCell(note.ref).note = noteOut(note);
-			for (const m of use("mergeCells") ? s.merges : []) if (m.includes(":")) ws.mergeCells(m);
+			for (const m of use("mergeCells") ? s.merges : []) {
+				if (!m.includes(":")) continue;
+				spend(areaOf(m), "A merged range", s.name);
+				ws.mergeCells(m);
+			}
 			if (use("sheetViews")) ws.views = [viewOut(s.view, s.freeze)];
 			const tab = colorOut(s.tabColor ?? void 0);
 			if (tab && use("sheetPr")) ws.properties["tabColor"] = tab;
@@ -6109,7 +6195,10 @@ var Workbook = class {
 			if (use("pageSetup")) ws.pageSetup = pageSetupOut(s.pageSetup, s.printArea, s.printTitles);
 			if (use("headerFooter")) ws.headerFooter = headerFooterOut(s.headerFooter);
 			if (use("rowBreaks")) ws.rowBreaks = rowBreaksOut(s.pageBreaks.rows);
-			for (const def of use("tableParts") ? s.tables : []) ws.tables[def.name] = tableOut(ws, def);
+			for (const def of use("tableParts") ? s.tables : []) {
+				spend(areaOf(def.ref), "A table", s.name);
+				ws.tables[def.name] = tableOut(ws, def);
+			}
 			for (const img of use("drawing") ? s.images : []) {
 				const id = img.image === null ? void 0 : mediaIds.get(img.image);
 				const media = id === void 0 ? null : imageOut(ws, img, id);
@@ -6123,6 +6212,42 @@ var Workbook = class {
 		}
 	}
 };
+/**
+* Worksheet ids for a list of wanted ids: each whole number from 1 to 65534 (the sheet ids Office
+* uses, W2-20) that is not wanted by an earlier entry is kept; other entries (missing, invalid,
+* larger or repeated ids) get the lowest ids no entry wants, in order. The limit keeps the
+* `_sheets` array small: an id from an untrusted file such as 4294967295 is not an array index and
+* 20000000 makes every scan of the array slow (found by review, D-F03). `undefined` entries
+* (sheets that are not worksheets) get no id.
+*/
+function freeIds(wanted) {
+	const taken = /* @__PURE__ */ new Set();
+	const kept = wanted.map((w) => {
+		if (typeof w !== "number" || !Number.isInteger(w) || w < 1 || w > 65534 || taken.has(w)) return null;
+		taken.add(w);
+		return w;
+	});
+	let next = 1;
+	return kept.map((k, i) => {
+		if (wanted[i] === void 0) return void 0;
+		if (k !== null) return k;
+		while (taken.has(next)) next++;
+		taken.add(next);
+		return next;
+	});
+}
+/** Cells in a range such as "A1:C3" (1 for a cell, 0 for anything else). */
+function areaOf(ref) {
+	const m = /^([A-Z]{1,3})(\d{1,7})(?::([A-Z]{1,3})(\d{1,7}))?$/.exec(ref.replace(/\$/g, ""));
+	if (!m) return 0;
+	const col = (letters) => {
+		let n = 0;
+		for (const ch of letters) n = n * 26 + ch.charCodeAt(0) - 64;
+		return n;
+	};
+	const [, c1 = "A", r1 = "1", c2 = c1, r2 = r1] = m;
+	return (Math.abs(Number(r2) - Number(r1)) + 1) * (Math.abs(col(c2) - col(c1)) + 1);
+}
 // src/stream.ts
 /**
 * A cell value for the streaming writer. Rows are written as they are committed, before later
@@ -6284,6 +6409,7 @@ var WorksheetWriter = class extends Worksheet {
 		return {
 			name: this.name,
 			state: this.state,
+			...sheetIdOf(this.id),
 			columns: trimTrailing(this.columns.map((c) => columnIn(c, this.writer._useStyles))),
 			...layout.freeze ? { freeze: layout.freeze } : {},
 			...Object.keys(layout.view).length > 0 ? { view: layout.view } : {},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xlvane/compat",
-  "version": "1.0.1",
+  "version": "1.1.1",
   "description": "The commonly used exceljs 4.4.0 API on top of xlvane, for switching with one line in package.json.",
   "keywords": [
     "xlsx",
@@ -72,7 +72,7 @@
     "build": "tsdown"
   },
   "dependencies": {
-    "xlvane": "^1.0.1"
+    "xlvane": "^1.1.1"
   },
   "publishConfig": {
     "access": "public",