sheetjs-formula-recalc 0.37.0

package/AGENTS.md

@@ -0,0 +1,36 @@
+# sheetjs-formula-recalc Agent Notes
+
+Use this package when a Node.js task already uses SheetJS or `xlsx` for workbook
+file I/O but needs fresh formula values after editing input cells.
+
+Start with the one-command proof:
+
+```sh
+npx --package sheetjs-formula-recalc sheetjs-recalc --demo --json
+```
+
+For a real workbook, use sheet-qualified A1 targets:
+
+```sh
+npx --package sheetjs-formula-recalc sheetjs-recalc quote.xlsx \
+  --set Inputs!B2=48 \
+  --read Summary!B7 \
+  --out quote.recalculated.xlsx \
+  --json
+```
+
+Use the API when code already has workbook bytes:
+
+```ts
+import { recalculateSheetjsWorkbook } from 'sheetjs-formula-recalc'
+
+const result = recalculateSheetjsWorkbook(xlsxBytes, {
+  edits: [{ target: 'Inputs!B2', value: 48 }],
+  reads: ['Summary!B7'],
+})
+```
+
+Do not claim this is a full Excel clone or a SheetJS replacement. Keep SheetJS
+for file I/O, review `result.warnings`, and reduce unsupported functions,
+external links, macros, and volatile formula cases into fixtures before
+promising production behavior.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) bilig contributors
+
+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,116 @@
+# sheetjs-formula-recalc
+
+Recalculate SheetJS / `xlsx` formula workbooks in Node.js without opening
+Excel, LibreOffice, or a browser.
+
+Use this package when the rest of your pipeline already uses SheetJS or the
+`xlsx` package for workbook file I/O, but a backend job needs fresh formula
+readback after changing inputs.
+
+## If You Arrived From a SheetJS Formula Issue
+
+SheetJS is good at reading and writing spreadsheet files. The common production
+gap is different:
+
+- `SheetJS formula result not updating`
+- `xlsx formula value stale after edit`
+- `js-xlsx recalculate formulas`
+- `refresh formula cells in xlsx node`
+
+Formula cells can carry cached results. When a Node process edits `Inputs!B2`,
+the cached value in `Summary!B7` is not automatically recalculated inside that
+process.
+
+Use this package at the file boundary:
+
+1. let SheetJS produce or update XLSX bytes;
+2. call `recalculateSheetjsWorkbook(...)`;
+3. read proof cells from `result.reads`;
+4. write `result.xlsx` if the updated artifact is needed.
+
+This package is a SheetJS-named bridge over `xlsx-formula-recalc`, so teams
+searching for a SheetJS answer can find the right boundary directly.
+
+## Install
+
+```sh
+npm install sheetjs-formula-recalc
+```
+
+## CLI
+
+Run a self-contained proof first:
+
+```sh
+npx --package sheetjs-formula-recalc sheetjs-recalc --demo --json
+```
+
+For a real workbook:
+
+```sh
+npx --package sheetjs-formula-recalc sheetjs-recalc quote.xlsx \
+  --set Inputs!B2=48 \
+  --set Inputs!B3=1500 \
+  --read Summary!B7 \
+  --out quote.recalculated.xlsx \
+  --json
+```
+
+The command writes the recalculated XLSX and prints the requested read cells.
+
+## TypeScript
+
+```ts
+import { readFile, writeFile } from 'node:fs/promises'
+import { recalculateSheetjsWorkbook } from 'sheetjs-formula-recalc'
+
+const result = recalculateSheetjsWorkbook(await readFile('quote.xlsx'), {
+  fileName: 'quote.xlsx',
+  edits: [
+    { target: 'Inputs!B2', value: 48 },
+    { target: 'Inputs!B3', value: 1500 },
+  ],
+  reads: ['Summary!B7'],
+})
+
+await writeFile('quote.recalculated.xlsx', result.xlsx)
+
+console.log({
+  value: result.reads['Summary!B7'],
+  warnings: result.warnings,
+})
+```
+
+## Proof Against SheetJS, xlsx-populate, and ExcelJS
+
+The repository includes a cross-library proof:
+
+```sh
+git clone https://github.com/proompteng/bilig.git
+cd bilig
+npm --prefix examples/recalc-bridge-workflows install
+npm --prefix examples/recalc-bridge-workflows run smoke
+```
+
+It edits the same workbook through SheetJS/`xlsx`, `xlsx-populate`, and
+ExcelJS, then verifies that Bilig refreshes the stale `48000` result to
+`72000`.
+
+## What This Is Not
+
+This is not a full Excel clone and not a replacement for SheetJS file I/O. Keep
+SheetJS where it is strongest: parsing, writing, and transforming workbook
+files. Add this package only where the Node process must own recalculated
+formula readback before accepting, rejecting, returning, or persisting a
+workflow.
+
+Review `result.warnings` and keep fixtures for unsupported functions, external
+workbook links, macros, volatile functions, and customer-critical templates.
+
+## Related
+
+- [SheetJS formula result not updating in Node.js](https://proompteng.github.io/bilig/sheetjs-formula-result-not-updating-node.html)
+- [XLSX formula recalculation in Node.js](https://proompteng.github.io/bilig/xlsx-formula-recalculation-node.html)
+- [SheetJS and ExcelJS boundary guide](https://proompteng.github.io/bilig/sheetjs-exceljs-alternative-formula-workbook-api.html)
+- [`xlsx-formula-recalc`](https://www.npmjs.com/package/xlsx-formula-recalc)
+- [`@bilig/headless`](https://www.npmjs.com/package/@bilig/headless)

package/SKILL.md

@@ -0,0 +1,38 @@
+# SheetJS Formula Recalculation
+
+Use `sheetjs-formula-recalc` when an agent or Node.js service has changed XLSX
+inputs through SheetJS / `xlsx` and must read recalculated formula outputs
+without opening Excel, LibreOffice, or a browser.
+
+## First Check
+
+```sh
+npx --package sheetjs-formula-recalc sheetjs-recalc --demo --json
+```
+
+The demo should print `verified: true` and a `Summary!B2` value of `72000`.
+
+## Real Workbook
+
+```sh
+npx --package sheetjs-formula-recalc sheetjs-recalc workbook.xlsx \
+  --set Inputs!B2=48 \
+  --read Summary!B7 \
+  --out workbook.recalculated.xlsx \
+  --json
+```
+
+## TypeScript
+
+```ts
+import { recalculateSheetjsWorkbook } from 'sheetjs-formula-recalc'
+
+const result = recalculateSheetjsWorkbook(inputXlsxBytes, {
+  edits: [{ target: 'Inputs!B2', value: 48 }],
+  reads: ['Summary!B7'],
+})
+```
+
+Use `xlsx-formula-recalc` when the caller does not care about SheetJS naming,
+and use `exceljs-formula-recalc` when the caller owns an ExcelJS `Workbook`
+object and wants read results patched back into that object.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { runXlsxFormulaRecalcCli } from 'xlsx-formula-recalc/cli-api';
+process.exitCode = runXlsxFormulaRecalcCli(process.argv.slice(2), {
+    commandName: 'sheetjs-recalc',
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,uBAAuB,EAAE,MAAM,6BAA6B,CAAA;AAErE,OAAO,CAAC,QAAQ,GAAG,uBAAuB,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE;IAChE,WAAW,EAAE,gBAAgB;CAC9B,CAAC,CAAA"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { WorkPaper, exportXlsx, importXlsx, parseQualifiedA1, parseQualifiedCellTarget, recalculateXlsx as recalculateSheetjsWorkbook, recalculateXlsx, } from 'xlsx-formula-recalc';
+export type { XlsxFormulaRecalcCellValue, XlsxFormulaRecalcEdit, XlsxFormulaRecalcOptions, XlsxFormulaRecalcResult, } from 'xlsx-formula-recalc';

package/dist/index.js

@@ -0,0 +1,2 @@
+export { WorkPaper, exportXlsx, importXlsx, parseQualifiedA1, parseQualifiedCellTarget, recalculateXlsx as recalculateSheetjsWorkbook, recalculateXlsx, } from 'xlsx-formula-recalc';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,SAAS,EACT,UAAU,EACV,UAAU,EACV,gBAAgB,EAChB,wBAAwB,EACxB,eAAe,IAAI,0BAA0B,EAC7C,eAAe,GAChB,MAAM,qBAAqB,CAAA"}

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "sheetjs-formula-recalc",
+  "version": "0.37.0",
+  "description": "Recalculate SheetJS and xlsx workbook formulas in Node.js without Excel, LibreOffice, or browser automation.",
+  "keywords": [
+    "excel",
+    "excel-formulas",
+    "formula-engine",
+    "formula-recalculation",
+    "js-xlsx",
+    "node",
+    "sheetjs",
+    "sheetjs-formula",
+    "sheetjs-recalc",
+    "spreadsheet",
+    "spreadsheet-formulas",
+    "workbook",
+    "xlsx",
+    "xlsx-calc",
+    "xlsx-formula",
+    "xlsx-formula-recalculation",
+    "xlsx-recalc",
+    "xlsx-recalculation"
+  ],
+  "homepage": "https://proompteng.github.io/bilig/sheetjs-formula-result-not-updating-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/sheetjs-formula-recalc"
+  },
+  "bin": {
+    "sheetjs-recalc": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "AGENTS.md",
+    "SKILL.md",
+    "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.37.0"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "build": "pnpm --dir ../.. --filter xlsx-formula-recalc build && rm -rf dist tsconfig.tsbuildinfo && tsc -p tsconfig.json",
+    "smoke": "node ./dist/cli.js --help"
+  }
+}