exceljs-formula-recalc 0.30.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Proompt Engineering
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,53 @@
+# exceljs-formula-recalc
+
+Recalculate formulas in an ExcelJS workbook without opening Excel, LibreOffice, or a browser.
+
+ExcelJS can read and write formula cells, but it does not run an Excel-compatible calculation engine for you after backend code edits inputs. This package bridges that gap: serialize the ExcelJS workbook, run the Bilig WorkPaper recalculation path, optionally load the recalculated XLSX back into the same ExcelJS workbook, and read proof values.
+
+## Install
+
+```sh
+npm install exceljs exceljs-formula-recalc
+```
+
+## Use With ExcelJS
+
+```ts
+import ExcelJS from "exceljs";
+import { recalculateExceljsWorkbook } from "exceljs-formula-recalc";
+
+const workbook = new ExcelJS.Workbook();
+await workbook.xlsx.readFile("quote.xlsx");
+
+const result = await recalculateExceljsWorkbook(workbook, {
+  edits: [
+    { target: "Inputs!B2", value: 48 },
+    { target: "Inputs!B3", value: 1500 },
+  ],
+  reads: ["Summary!B7"],
+});
+
+console.log(result.reads["Summary!B7"]);
+await workbook.xlsx.writeFile("quote.recalculated.xlsx");
+```
+
+By default, `recalculateExceljsWorkbook` mutates the provided ExcelJS workbook by loading the recalculated XLSX bytes back into it. For targets listed in `reads`, it also patches the ExcelJS formula cell object with the recalculated `result`, so backend code can inspect proof values without reopening the file. Pass `mutateWorkbook: false` if you only need the returned `xlsx` bytes.
+
+## API
+
+```ts
+import {
+  recalculateExceljsBuffer,
+  recalculateExceljsWorkbook,
+} from "exceljs-formula-recalc";
+```
+
+`recalculateExceljsWorkbook(workbook, options)` accepts any workbook-like object with `workbook.xlsx.writeBuffer()` and `workbook.xlsx.load(...)`, which matches ExcelJS workbooks.
+
+`recalculateExceljsBuffer(input, options)` accepts XLSX bytes and returns the same result shape as `xlsx-formula-recalc`.
+
+Cell targets must be sheet-qualified A1 references such as `Inputs!B2` or `'Pricing Model'!F12`.
+
+## Scope
+
+Use this when a Node service already uses ExcelJS for workbook I/O but needs deterministic formula readback after changing inputs. It is not a full Excel clone: unsupported Excel functions, external workbook links, macros, and volatile functions may need review. Import warnings are returned in `result.warnings`.

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+import { type XlsxFormulaRecalcOptions, type XlsxFormulaRecalcResult } from 'xlsx-formula-recalc';
+export { WorkPaper, exportXlsx, importXlsx, parseQualifiedA1, parseQualifiedCellTarget, recalculateXlsx } from 'xlsx-formula-recalc';
+export type { XlsxFormulaRecalcCellValue, XlsxFormulaRecalcEdit, XlsxFormulaRecalcOptions, XlsxFormulaRecalcResult, } from 'xlsx-formula-recalc';
+export interface ExceljsWorkbookLike {
+    readonly xlsx: {
+        writeBuffer(): Promise<ArrayBuffer | Buffer | Uint8Array>;
+        load(input: ArrayBuffer | Buffer | Uint8Array): Promise<unknown>;
+    };
+    getWorksheet?(name: string): ExceljsWorksheetLike | undefined;
+}
+export interface ExceljsWorksheetLike {
+    getCell(address: string): ExceljsCellLike;
+}
+export interface ExceljsCellLike {
+    value: unknown;
+}
+export interface ExceljsFormulaRecalcOptions extends XlsxFormulaRecalcOptions {
+    readonly mutateWorkbook?: boolean;
+}
+export interface ExceljsFormulaRecalcResult extends XlsxFormulaRecalcResult {
+    readonly workbookMutated: boolean;
+}
+export declare function recalculateExceljsWorkbook(workbook: ExceljsWorkbookLike, options?: ExceljsFormulaRecalcOptions): Promise<ExceljsFormulaRecalcResult>;
+export declare function recalculateExceljsBuffer(input: Uint8Array | ArrayBuffer | Buffer, options?: XlsxFormulaRecalcOptions): XlsxFormulaRecalcResult;

package/dist/index.js

@@ -0,0 +1,70 @@
+import { parseQualifiedA1, recalculateXlsx } from 'xlsx-formula-recalc';
+export { WorkPaper, exportXlsx, importXlsx, parseQualifiedA1, parseQualifiedCellTarget, recalculateXlsx } from 'xlsx-formula-recalc';
+export async function recalculateExceljsWorkbook(workbook, options = {}) {
+    const { mutateWorkbook = true, ...recalcOptions } = options;
+    const input = await workbook.xlsx.writeBuffer();
+    const result = recalculateXlsx(toUint8Array(input), recalcOptions);
+    if (mutateWorkbook) {
+        await workbook.xlsx.load(result.xlsx);
+        patchExceljsReadResults(workbook, result.reads);
+    }
+    return {
+        ...result,
+        workbookMutated: mutateWorkbook,
+    };
+}
+export function recalculateExceljsBuffer(input, options = {}) {
+    return recalculateXlsx(input, options);
+}
+function toUint8Array(input) {
+    if (input instanceof Uint8Array) {
+        return input;
+    }
+    return new Uint8Array(input);
+}
+function patchExceljsReadResults(workbook, reads) {
+    if (!workbook.getWorksheet) {
+        return;
+    }
+    for (const [target, value] of Object.entries(reads)) {
+        const parsed = parseQualifiedA1(target);
+        const worksheet = workbook.getWorksheet(parsed.sheetName);
+        if (!worksheet) {
+            continue;
+        }
+        const cell = worksheet.getCell(`${columnIndexToLetters(parsed.col)}${parsed.row + 1}`);
+        const readValue = unwrapReadValue(value);
+        if (readValue === undefined) {
+            continue;
+        }
+        if (isExceljsFormulaCellValue(cell.value)) {
+            cell.value = {
+                ...cell.value,
+                result: readValue,
+            };
+        }
+        else {
+            cell.value = readValue;
+        }
+    }
+}
+function unwrapReadValue(value) {
+    if (typeof value === 'object' && value !== null && 'value' in value) {
+        return value.value;
+    }
+    return undefined;
+}
+function isExceljsFormulaCellValue(value) {
+    return typeof value === 'object' && value !== null && 'formula' in value && typeof value.formula === 'string';
+}
+function columnIndexToLetters(columnIndex) {
+    let value = columnIndex + 1;
+    let letters = '';
+    while (value > 0) {
+        const remainder = (value - 1) % 26;
+        letters = String.fromCharCode(65 + remainder) + letters;
+        value = Math.floor((value - 1) / 26);
+    }
+    return letters;
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "exceljs-formula-recalc",
+  "version": "0.30.2",
+  "description": "Recalculate ExcelJS XLSX workbook formulas in Node.js without Excel, LibreOffice, or browser automation.",
+  "keywords": [
+    "excel",
+    "excel-formulas",
+    "exceljs",
+    "exceljs-formulas",
+    "exceljs-recalc",
+    "formula-engine",
+    "formula-recalculation",
+    "node",
+    "spreadsheet",
+    "workbook",
+    "xlsx",
+    "xlsx-formula",
+    "xlsx-recalc",
+    "xlsx-recalculation"
+  ],
+  "homepage": "https://proompteng.github.io/bilig/exceljs-formula-recalculation-node.html",
+  "bugs": {
+    "url": "https://github.com/proompteng/bilig/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/proompteng/bilig.git",
+    "directory": "packages/exceljs-formula-recalc"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "xlsx-formula-recalc": "0.30.2"
+  },
+  "devDependencies": {
+    "exceljs": "4.4.0"
+  },
+  "peerDependencies": {
+    "exceljs": ">=4.4.0"
+  },
+  "peerDependenciesMeta": {
+    "exceljs": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "build": "pnpm --dir ../.. --filter xlsx-formula-recalc build && rm -rf dist tsconfig.tsbuildinfo && tsc -p tsconfig.json"
+  }
+}