@libraz/formulon 0.9.6 → 0.10.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,8 +1,14 @@
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
- loads and saves `.xlsx` workbooks, and aims for 1-bit compatibility with
5
- Mac Excel 365 (ja-JP locale).
9
+ loads and saves `.xlsx` workbooks, and defaults to the `win-365-ja_JP`
10
+ behavior profile. Hosts can select the separately supported
11
+ `mac-365-ja_JP` profile when required.
6
12
 
7
13
  ## Install
8
14
 
@@ -67,8 +73,8 @@ try {
67
73
  The package ships a single ES module factory plus the companion
68
74
  `formulon.wasm`. Two consumer-side concerns are worth knowing about:
69
75
 
70
- **1. Pthread workers require ES module workers.** Internally the engine
71
- 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
72
78
  `new Worker(new URL("formulon.js", import.meta.url), {type: "module"})`.
73
79
  Bundlers default to classic (IIFE) workers and must be told otherwise:
74
80
 
@@ -118,6 +124,20 @@ hosting in a browser, serve the page with `Cross-Origin-Opener-Policy:
118
124
  same-origin` and `Cross-Origin-Embedder-Policy: require-corp` headers,
119
125
  or pthread workers will refuse to start.
120
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
+
121
141
  ## API reference
122
142
 
123
143
  The full TypeScript surface is shipped as `dist/formulon.d.ts` and is the
@@ -131,17 +151,31 @@ authoritative reference. Highlights:
131
151
  factory methods for building or loading a workbook.
132
152
  - `Workbook.setNumber / setBool / setText / setBlank / setFormula` --
133
153
  cell mutators.
134
- - `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.
135
158
  - `Workbook.getValue(sheet, row, col)` -- reads a cached cell value.
136
159
  - `Workbook.save()` -- serialises back to an in-memory `.xlsx` byte buffer.
137
160
 
138
161
  Workbook handles wrap a native pointer; always call `wb.delete()` (in a
139
162
  `finally` block) when done.
140
163
 
164
+ ## Memory when loading a workbook
165
+
166
+ `loadBytes` reads worksheet XML through the DOM parser only. The native
167
+ CLI switches to a streaming parser for worksheets past 256 KiB; that
168
+ implementation costs binary size the WASM budget does not have, so
169
+ loading here needs memory proportional to the largest single worksheet's
170
+ XML rather than a fixed window. Sheets are read one at a time, so the
171
+ peak is per worksheet, and the practical ceiling is the 32-bit WASM
172
+ address space. Results are identical either way.
173
+
141
174
  ## Project
142
175
 
143
- Source, design notes, and the oracle test suite live at
144
- <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>.
145
179
 
146
180
  ## License
147
181