@xlvane/compat 1.0.0 → 1.1.0

package/README.md

@@ -1,6 +1,6 @@
 # @xlvane/compat
 
-The [exceljs](https://github.com/exceljs/exceljs) 4.4.0 API, built on [xlvane](https://www.npmjs.com/package/xlvane), with the differences listed in docs/exceljs-compat.md (link below). Code written for exceljs keeps working after one change in `package.json`:
+The [exceljs](https://github.com/exceljs/exceljs) 4.4.0 API, built on [xlvane](https://www.npmjs.com/package/xlvane), with the differences listed below and in [docs/exceljs-compat.md](https://github.com/DevXord/xlvane/blob/main/docs/exceljs-compat.md). Code written for exceljs keeps working after one change in `package.json`:
 
 ```json
 "dependencies": {
@@ -8,8 +8,29 @@ The [exceljs](https://github.com/exceljs/exceljs) 4.4.0 API, built on [xlvane](h
 }
 ```
 
+npm installs the package under the name `exceljs` (an npm alias), so `import ExcelJS from 'exceljs'` and `require('exceljs')` load `@xlvane/compat` and the code stays unchanged.
+
+## Installing
+
+In a project that uses exceljs, either install the alias:
+
+```sh
+npm install exceljs@npm:@xlvane/compat@^1
+```
+
+or let the `xlvane` command line prepare the project:
+
+```sh
+npx xlvane migrate              # report: the change to package.json and places in the code to check
+npx xlvane migrate --force      # change package.json, then run npm install
+```
+
+`xlvane migrate` changes only `package.json`, and only with `--force`. It scans the files that mention exceljs for API outside the supported subset; the matching is textual, so a finding is a place to look at.
+
+## Example
+
 ```js
-import ExcelJS from 'exceljs'; // or: const ExcelJS = require('exceljs');
+import ExcelJS from 'exceljs';
 
 const workbook = new ExcelJS.Workbook();
 const sheet = workbook.addWorksheet('Sales');
@@ -21,10 +42,34 @@ sheet.addRow({ region: 'North', revenue: 1200 });
 await workbook.xlsx.writeFile('sales.xlsx');
 ```
 
-- Requires Node.js 22.12 or later for `require()` (the package is an ES module; `require()` of ES modules works without a flag from 22.12). ESM `import` works the same way, and named imports such as `import { Workbook } from 'exceljs'` work too.
-- The few exceljs features that are not offered (row and column operations on a streamed worksheet, which exceljs itself does not have, and deep imports of exceljs internals such as `exceljs/lib/...`) throw an `XlvError` with code `XLV_E_NOT_SUPPORTED` and the name of the feature, or fail to resolve. Nothing is dropped silently.
-- What is supported, partly supported and not supported, with the source of each exceljs behaviour: [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). Errors are described in `node_modules/xlvane/docs/errors.md`.
+In CommonJS, `const ExcelJS = require('exceljs');` gives the same object; call `writeFile` inside an async function there.
+
+## Requirements
+
+- Node.js 22.12 or later (`engines.node`). The package is an ES module; `require()` of ES modules works without a flag from Node.js 22.12. Named imports such as `import { Workbook } from 'exceljs'` work too.
+- The same test bundle runs in Node.js 22, 24 and 26, Bun, Deno, Chromium and the Cloudflare Workers runtime (workerd). Methods that read or write files (`xlsx.readFile`, `xlsx.writeFile`, `csv.readFile`, `csv.writeFile`, the `filename` forms of the streaming classes and of `addImage`) work in Node.js, Bun and Deno; in browsers and Workers they throw `XLV_E_NOT_SUPPORTED`, and a bundler leaves the file helpers out.
+- Dependencies: `xlvane` only, which depends on `fflate` only.
+- TypeScript: the type names of exceljs's `index.d.ts` are exported (`ExcelJS.Worksheet`, `ExcelJS.Fill`, …) and work with `moduleResolution` `bundler` and `nodenext` and with `module: commonjs`. In a CommonJS project, TypeScript refuses `import ExcelJS = require('exceljs')` of an ES module under `module: node16` (TS1471); use `nodenext` or `commonjs`.
+
+## Differences from exceljs
+
+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:** `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).
+- **Input files** are treated as untrusted, as in xlvane: ZIP and XML limits, no DTDs or external entities. A file over a limit is rejected with an `XlvError` (`XLV_E_*` code, location and hint; `node_modules/xlvane/docs/errors.md`).
+
+## Links
+
+- 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)
 
-@xlvane/compat is an independent project. It is not affiliated with or endorsed by the exceljs project or its authors, and it contains no exceljs code; its API and type declarations follow exceljs 4.4.0, whose MIT license notice is included in LICENSE.
+## License
 
-License: MIT
+MIT. @xlvane/compat is an independent project. It is not affiliated with or endorsed by the exceljs project or its authors, and it contains no exceljs code; its API and type declarations follow exceljs 4.4.0, whose MIT license notice is included in LICENSE.

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;

package/dist/index.js

@@ -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;
@@ -5844,7 +5857,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 +5932,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"] : [];
@@ -6030,9 +6048,10 @@ 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);
@@ -6123,6 +6142,30 @@ 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;
+	});
+}
 // src/stream.ts
 /**
 * A cell value for the streaming writer. Rows are written as they are committed, before later
@@ -6284,6 +6327,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.0",
+  "version": "1.1.0",
   "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.0"
+    "xlvane": "^1.1.0"
   },
   "publishConfig": {
     "access": "public",