@bilig/xlsx-formula-recalc 0.161.0 → 0.164.0

package/AGENTS.md

@@ -68,17 +68,23 @@ npm exec --yes --package @bilig/xlsx-formula-recalc@latest -- xlsx-recalc quote.
   --json
 ```
 
-Use the API when code already has workbook bytes:
+Use the production API when code has input and output file paths. The root
+package path is file-backed and uses the native streaming engine first:
 
 ```ts
-import { recalculateXlsx } from '@bilig/xlsx-formula-recalc'
+import { recalculateXlsxFileToFile } from '@bilig/xlsx-formula-recalc'
 
-const result = recalculateXlsx(xlsxBytes, {
+const result = await recalculateXlsxFileToFile('quote.xlsx', {
+  outputPath: 'quote.recalculated.xlsx',
   edits: [{ target: 'Inputs!B2', value: 48 }],
   reads: ['Summary!B7'],
+  engine: 'streaming-native',
 })
 ```
 
+The older bytes-in/bytes-out WorkPaper API is explicit legacy compatibility:
+import it from `@bilig/workpaper/xlsx` and install `@bilig/workpaper` when that fallback is intentional.
+
 Do not claim this is a full Excel clone. Review `result.warnings` and reduce
 unsupported functions, external links, macros, and volatile formula cases into
 fixtures before promising production behavior.

package/README.md

@@ -146,9 +146,10 @@ That is the failure behind issues and searches like:
 Use this package at the file boundary:
 
 1. let your existing library produce XLSX bytes;
-2. call `recalculateXlsx(...)`;
-3. read the proof cells from `result.reads`;
-4. write `result.xlsx` if the recalculated workbook artifact is needed.
+2. write them to the XLSX file path your service owns;
+3. call `recalculateXlsxFileToFile(...)`;
+4. read the proof cells from `result.reads`;
+5. return the recalculated output file.
 
 That keeps your current file-writer choice intact and adds only the missing
 calculation/readback step.
@@ -271,15 +272,15 @@ run
 
 ## API
 
-Use `inspectXlsxCache` when a service or test runner needs the cache-doctor
-report without shelling out to the CLI:
+Use `inspectXlsxCacheFile` when a service or test runner needs the
+cache-doctor report without shelling out to the CLI. It stays on the same
+file-backed streaming-native path as `xlsx-cache-doctor`:
 
 ```ts
-import { readFile } from 'node:fs/promises'
-import { inspectXlsxCache } from '@bilig/xlsx-formula-recalc'
+import { inspectXlsxCacheFile } from '@bilig/xlsx-formula-recalc'
 
-const report = inspectXlsxCache(await readFile('pricing.xlsx'), {
-  fileName: 'pricing.xlsx',
+const report = await inspectXlsxCacheFile('pricing.xlsx', {
+  maxRssBytes: 350 * 1024 * 1024,
 })
 
 if (report.staleCachedFormulaCount > 0) {
@@ -296,41 +297,50 @@ The API returns the same `schemaVersion`, `cacheStatusSummary`, per-formula
 `cacheStatus`, and `suggestedReads` fields as the JSON CLI report.
 
 ```ts
-import { recalculateXlsx } from '@bilig/xlsx-formula-recalc'
+import { recalculateXlsxFileToFile } from '@bilig/xlsx-formula-recalc'
 
-const result = recalculateXlsx(await fs.promises.readFile('pricing.xlsx'), {
+const result = await recalculateXlsxFileToFile('pricing.xlsx', {
+  outputPath: 'pricing.recalculated.xlsx',
   edits: [
     { target: 'Inputs!B2', value: 48 },
     { target: 'Inputs!B3', value: 1500 },
   ],
   reads: ['Summary!B7'],
+  engine: 'streaming-native',
 })
 
-await fs.promises.writeFile('pricing.recalculated.xlsx', result.xlsx)
 console.log(result.reads['Summary!B7'])
 ```
 
-External companion workbooks use the same matching rules as the CLI:
+External companion workbooks stay on the native file-to-file path:
 
 ```ts
-const result = recalculateXlsx(await fs.promises.readFile('model.xlsx'), {
+import { readFile } from 'node:fs/promises'
+
+import { recalculateXlsxFileToFile } from '@bilig/xlsx-formula-recalc'
+
+const result = await recalculateXlsxFileToFile('model.xlsx', {
+  outputPath: 'model.recalculated.xlsx',
   externalWorkbooks: [
     {
-      bytes: await fs.promises.readFile('rates.xlsx'),
+      bytes: await readFile('rates.xlsx'),
       fileName: 'rates.xlsx',
       target: 'file:///tmp/rates.xlsx',
     },
   ],
   reads: ['Model!C1'],
+  engine: 'streaming-native',
 })
 
 console.log(result.diagnostics?.externalWorkbookHydration)
 ```
 
-If another library already produced the workbook bytes, pass those bytes
-directly:
+If another library already produced workbook bytes instead of a file path, use
+the explicit legacy compatibility import:
 
 ```ts
+import { recalculateXlsx } from '@bilig/workpaper/xlsx'
+
 const output = await workbook.outputAsync('nodebuffer') // for example, from xlsx-populate
 
 const result = recalculateXlsx(output, {
@@ -338,8 +348,10 @@ const result = recalculateXlsx(output, {
 })
 ```
 
-For the full workbook API, import `WorkPaper`, `importXlsx`, and `exportXlsx`
-from `@bilig/workpaper`.
+For the full workbook API, use `@bilig/workpaper`. For the old bytes-in,
+bytes-out compatibility API, import from
+`@bilig/workpaper/xlsx` and install `@bilig/workpaper`
+explicitly.
 
 ## Common Boundaries
 

package/SKILL.md

@@ -97,13 +97,19 @@ npm exec --yes --package @bilig/xlsx-formula-recalc@latest -- xlsx-recalc workbo
 ## TypeScript
 
 ```ts
-import { recalculateXlsx } from '@bilig/xlsx-formula-recalc'
+import { recalculateXlsxFileToFile } from '@bilig/xlsx-formula-recalc'
 
-const result = recalculateXlsx(inputXlsxBytes, {
+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.

package/dist/cache-doctor-cli.js

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

package/dist/cache-doctor-cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cache-doctor-cli.js","sourceRoot":"","sources":["../src/cache-doctor-cli.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAA;AAEtD,OAAO,CAAC,QAAQ,GAAG,uBAAuB,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE;IAChE,WAAW,EAAE,mBAAmB;CACjC,CAAC,CAAA"}
+{"version":3,"file":"cache-doctor-cli.js","sourceRoot":"","sources":["../src/cache-doctor-cli.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,4BAA4B,EAAE,MAAM,cAAc,CAAA;AAE3D,OAAO,CAAC,QAAQ,GAAG,MAAM,4BAA4B,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE;IAC3E,WAAW,EAAE,mBAAmB;CACjC,CAAC,CAAA"}

package/dist/cli.js

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

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAA;AAEtD,OAAO,CAAC,QAAQ,GAAG,uBAAuB,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE;IAChE,WAAW,EAAE,aAAa;CAC3B,CAAC,CAAA"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,4BAA4B,EAAE,MAAM,cAAc,CAAA;AAE3D,OAAO,CAAC,QAAQ,GAAG,MAAM,4BAA4B,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE;IAC3E,WAAW,EAAE,aAAa;CAC3B,CAAC,CAAA"}

package/dist/evaluator-bin.js

@@ -1,3 +1,3 @@
 import { runBiligEvaluatorCli } from 'xlsx-formula-recalc/evaluator';
-process.exitCode = runBiligEvaluatorCli(process.argv.slice(2));
+process.exitCode = await runBiligEvaluatorCli(process.argv.slice(2));
 //# sourceMappingURL=evaluator-bin.js.map

package/dist/evaluator-bin.js.map

@@ -1 +1 @@
-{"version":3,"file":"evaluator-bin.js","sourceRoot":"","sources":["../src/evaluator-bin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAA;AAEpE,OAAO,CAAC,QAAQ,GAAG,oBAAoB,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAA"}
+{"version":3,"file":"evaluator-bin.js","sourceRoot":"","sources":["../src/evaluator-bin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAA;AAEpE,OAAO,CAAC,QAAQ,GAAG,MAAM,oBAAoB,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAA"}

package/dist/sheetjs-cli.js

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

package/dist/sheetjs-cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"sheetjs-cli.js","sourceRoot":"","sources":["../src/sheetjs-cli.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAA;AAEtD,OAAO,CAAC,QAAQ,GAAG,uBAAuB,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE;IAChE,WAAW,EAAE,gBAAgB;CAC9B,CAAC,CAAA"}
+{"version":3,"file":"sheetjs-cli.js","sourceRoot":"","sources":["../src/sheetjs-cli.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,4BAA4B,EAAE,MAAM,cAAc,CAAA;AAE3D,OAAO,CAAC,QAAQ,GAAG,MAAM,4BAA4B,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE;IAC3E,WAAW,EAAE,gBAAgB;CAC9B,CAAC,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bilig/xlsx-formula-recalc",
-  "version": "0.161.0",
+  "version": "0.164.0",
   "description": "Diagnose stale cached XLSX formula values and recalculate XLSX formulas in Node.js without Excel, LibreOffice, or browser automation.",
   "keywords": [
     "bilig",
@@ -88,7 +88,7 @@
     "smoke": "node ./dist/cli.js --help"
   },
   "dependencies": {
-    "xlsx-formula-recalc": "0.161.0"
+    "xlsx-formula-recalc": "0.164.0"
   },
   "engines": {
     "node": ">=22.0.0"