@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 +41 -7
- package/dist/formulon.d.ts +538 -90
- package/dist/formulon.js +99 -18
- package/dist/formulon.wasm +0 -0
- package/dist/formulon_core.js +2 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,8 +1,14 @@
|
|
|
1
1
|
# @libraz/formulon
|
|
2
2
|
|
|
3
|
+
[](https://www.npmjs.com/package/@libraz/formulon)
|
|
4
|
+
[](https://pypi.org/project/formulon/)
|
|
5
|
+
[](https://github.com/libraz/formulon/blob/main/LICENSE)
|
|
6
|
+
[](https://formulon.libraz.net)
|
|
7
|
+
|
|
3
8
|
Excel 365 calculation engine, compiled to WebAssembly. Evaluates formulas,
|
|
4
|
-
loads and saves `.xlsx` workbooks, and
|
|
5
|
-
|
|
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.
|
|
71
|
-
runs
|
|
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
|
|
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
|
-
|
|
144
|
-
<https://
|
|
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
|
|