@libraz/formulon 0.9.7 → 0.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,5 +1,10 @@
1
1
  # @libraz/formulon
2
2
 
3
+ [![npm](https://img.shields.io/npm/v/@libraz/formulon)](https://www.npmjs.com/package/@libraz/formulon)
4
+ [![PyPI](https://img.shields.io/pypi/v/formulon)](https://pypi.org/project/formulon/)
5
+ [![License](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/libraz/formulon/blob/main/LICENSE)
6
+ [![Docs](https://img.shields.io/badge/docs-formulon.libraz.net-2563eb)](https://formulon.libraz.net)
7
+
3
8
  Excel 365 calculation engine, compiled to WebAssembly. Evaluates formulas,
4
9
  loads and saves `.xlsx` workbooks, and defaults to the `win-365-ja_JP`
5
10
  behavior profile. Hosts can select the separately supported
@@ -68,8 +73,8 @@ try {
68
73
  The package ships a single ES module factory plus the companion
69
74
  `formulon.wasm`. Two consumer-side concerns are worth knowing about:
70
75
 
71
- **1. Pthread workers require ES module workers.** Internally the engine
72
- runs the recalc scheduler on Web Workers spawned by Emscripten with
76
+ **1. `recalcParallel` requires ES module workers.** The parallel recalc
77
+ scheduler runs on Web Workers spawned by Emscripten with
73
78
  `new Worker(new URL("formulon.js", import.meta.url), {type: "module"})`.
74
79
  Bundlers default to classic (IIFE) workers and must be told otherwise:
75
80
 
@@ -119,6 +124,20 @@ hosting in a browser, serve the page with `Cross-Origin-Opener-Policy:
119
124
  same-origin` and `Cross-Origin-Embedder-Policy: require-corp` headers,
120
125
  or pthread workers will refuse to start.
121
126
 
127
+ ### Parallel recalculation
128
+
129
+ `Workbook.recalc()` remains the serial, caller-thread recalculation API.
130
+ `Workbook.recalcParallel(threadCount)` is synchronous and returns a
131
+ `{ status, stats }` result after all workers have joined. A thread count of
132
+ `0` selects automatic detection capped at 8, `1` keeps all evaluation on the
133
+ caller thread and starts no workers, and `2..8` sets the maximum worker count.
134
+ Values above 8 return a failed status with `kInvalidArgument`.
135
+
136
+ The five 64-bit scheduler counters in `stats` are surfaced as JavaScript
137
+ `number` values (not `bigint`) and are exact through `Number.MAX_SAFE_INTEGER`
138
+ (`2^53 - 1`). `workerThreadsStarted` and `workerThreadsUsed` report actual
139
+ worker telemetry; the scheduler may use fewer workers than requested.
140
+
122
141
  ## API reference
123
142
 
124
143
  The full TypeScript surface is shipped as `dist/formulon.d.ts` and is the
@@ -132,7 +151,10 @@ authoritative reference. Highlights:
132
151
  factory methods for building or loading a workbook.
133
152
  - `Workbook.setNumber / setBool / setText / setBlank / setFormula` --
134
153
  cell mutators.
135
- - `Workbook.recalc()` -- triggers a full dependency-ordered recalculation.
154
+ - `Workbook.recalc()` -- triggers a serial, full dependency-ordered
155
+ recalculation.
156
+ - `Workbook.recalcParallel(threadCount)` -- synchronously recalculates with
157
+ the parallel SCC scheduler and returns status plus telemetry.
136
158
  - `Workbook.getValue(sheet, row, col)` -- reads a cached cell value.
137
159
  - `Workbook.save()` -- serialises back to an in-memory `.xlsx` byte buffer.
138
160
 
@@ -151,8 +173,9 @@ address space. Results are identical either way.
151
173
 
152
174
  ## Project
153
175
 
154
- Source, design notes, and the oracle test suite live at
155
- <https://github.com/libraz/formulon>.
176
+ Documentation — guides, compatibility notes, and the per-runtime API
177
+ reference — is at <https://formulon.libraz.net>. Source, design notes,
178
+ and the oracle test suite live at <https://github.com/libraz/formulon>.
156
179
 
157
180
  ## License
158
181