XLSX Formula Recalc

XLSX Formula Recalculation

Use @bilig/xlsx-formula-recalc when an agent or Node.js service has changed XLSX inputs and must read recalculated formula outputs without opening Excel, LibreOffice, or a browser. The unscoped xlsx-formula-recalc package remains a compatibility/search alias; new agent instructions should use the scoped package first.

First Check

npm exec --yes --package @bilig/xlsx-formula-recalc@latest -- bilig-evaluate --door xlsx-cache --json

The evaluator should print schemaVersion: "bilig-evaluator.v1", door: "xlsx-cache", verified: true, and evidence for a stale cached formula corrected to a Summary!B2 value of 72000.

For SheetJS / xlsx stale-formula issues, use the SheetJS-named binary from the same package:

npm exec --yes --package @bilig/xlsx-formula-recalc@latest -- sheetjs-recalc --demo --json

If you have a real workbook but do not yet know which formula cells to verify, inspect it without writing an output file:

npm exec --yes --package @bilig/xlsx-formula-recalc@latest -- xlsx-recalc workbook.xlsx --inspect --json

For CI or issue triage, use the cache-diagnosis alias:

npm exec --yes --package @bilig/xlsx-formula-recalc@latest -- xlsx-cache-doctor workbook.xlsx --json

The inspection output includes formulaCellCount, staleCachedFormulaCount, suggestedReads, and a nextStep.command for the recalculation proof. Default inspection checks every formula. If a workflow sets --inspect-limit, require uninspectedFormulaCellCount: 0 before treating the report as complete coverage.

Real Workbook

npm exec --yes --package @bilig/xlsx-formula-recalc@latest -- xlsx-recalc workbook.xlsx \
  --set Inputs!B2=48 \
  --read Summary!B7 \
  --out workbook.recalculated.xlsx \
  --json

For linked workbooks, pass companion files:

npm exec --yes --package @bilig/xlsx-formula-recalc@latest -- xlsx-recalc workbook.xlsx \
  --external-workbook rates.xlsx \
  --read Summary!B7 \
  --json

Use an exact target binding when the workbook link target differs from the local filename:

npm exec --yes --package @bilig/xlsx-formula-recalc@latest -- xlsx-recalc workbook.xlsx \
  --external-workbook-target ./fixtures/rates-current.xlsx file:///tmp/rates.xlsx \
  --read Summary!B7 \
  --json

TypeScript

import { recalculateXlsx } from '@bilig/xlsx-formula-recalc'

const result = recalculateXlsx(inputXlsxBytes, {
  edits: [{ target: 'Inputs!B2', value: 48 }],
  reads: ['Summary!B7'],
})

Prefer exceljs-formula-recalc when the caller already owns an ExcelJS Workbook object and wants read results patched back into that object.