Bilig Xlsx Formula Recalc

---
name: bilig-xlsx-formula-recalc
version: 0.1.0
description: Recalculate XLSX formula outputs in Node.js after cell edits without opening Excel, LibreOffice, or browser automation.
tags:
  - xlsx
  - excel
  - formula-recalculation
  - node
  - spreadsheet-automation
  - typescript
---

# Bilig 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. This package is the canonical scoped package.

## First Check

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

Use `workbook-compatibility` when you need a local preflight report for a real
workbook before a Node service or agent trusts it. The report lists unsupported
functions, external links, macro payloads, pivots, volatile functions, stale
caches, and concrete risk reasons. It does not certify Excel compatibility and
must not grow a compatibility score.

The cache 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:

```sh
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:

```sh
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:

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

For workbook risk review, use the compatibility report:

```sh
npm exec --yes --package @bilig/xlsx-formula-recalc@latest -- workbook-compatibility-report workbook.xlsx --json
```

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

## Real Workbook

```sh
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:

```sh
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:

```sh
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

```ts
import { recalculateXlsxFileToFile } from '@bilig/xlsx-formula-recalc'

const result = await recalculateXlsxFileToFile('workbook.xlsx', {
  outputPath: 'workbook.recalculated.xlsx',
  edits: [{ target: 'Inputs!B2', value: 48 }],
  reads: ['Summary!B7'],
  engine: 'streaming-native',
})
```

For the older bytes-in/bytes-out WorkPaper path, import from
`@bilig/workpaper/xlsx` and install `@bilig/workpaper`
explicitly.

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