@libraz/formulon 0.13.0 โ 0.15.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 +58 -165
- package/dist/common.js +3 -2
- package/dist/formulon.d.ts +370 -40
- package/dist/formulon.wasm +0 -0
- package/dist/formulon_core.js +1 -1
- package/dist/formulon_threads.wasm +0 -0
- package/dist/formulon_threads_core.js +1 -1
- package/package.json +9 -3
package/README.md
CHANGED
|
@@ -5,18 +5,28 @@
|
|
|
5
5
|
[](https://github.com/libraz/formulon/blob/main/LICENSE)
|
|
6
6
|
[](https://formulon.libraz.net)
|
|
7
7
|
|
|
8
|
-
Excel
|
|
9
|
-
|
|
10
|
-
behavior profile. Hosts can select the separately supported
|
|
11
|
-
`mac-365-ja_JP` profile when required.
|
|
8
|
+
**Recalculate Excel workbooks and formulas in the browser and Node, with results checked against real Excel 365.**
|
|
9
|
+
The engine is a C++17 core compiled to WebAssembly, so it needs no Excel install, no Windows and no server: a workbook a user opens in the page is calculated on their machine and never uploaded.
|
|
12
10
|
|
|
13
|
-
|
|
11
|
+
Known differences from Excel are listed case by case in [`tests/divergence.yaml`](https://github.com/libraz/formulon/blob/main/tests/divergence.yaml), each with a reason and the Excel build it was last verified on.
|
|
14
12
|
|
|
15
|
-
|
|
16
|
-
|
|
13
|
+
๐ **[Documentation](https://formulon.libraz.net)** ยท **[WASM guide](https://formulon.libraz.net/runtimes/wasm)** ยท **[API](https://formulon.libraz.net/api/wasm)** ยท **[Demos](https://formulon.libraz.net/demos)**
|
|
14
|
+
|
|
15
|
+
## What's inside
|
|
16
|
+
|
|
17
|
+
- **Formula engine** โ 526 Excel function names, 511 implemented locally; dynamic arrays, `LET` / `LAMBDA`, and `REGEX*`. [Coverage](https://formulon.libraz.net/compatibility/formula-coverage)
|
|
18
|
+
- **Workbook I/O** โ read, recalculate and write `.xlsx` and `.xlsb`, including styles, conditional formatting, tables, pivot tables and print layout. [File formats](https://formulon.libraz.net/compatibility/file-format-support)
|
|
19
|
+
- **Locale profiles** โ 28 Excel behavior profiles across fourteen locales on Mac and Windows hosts. [Locale profiles](https://formulon.libraz.net/compatibility/locale-profiles)
|
|
20
|
+
- **Excel oracle** โ formula results are compared bit for bit against goldens captured from Mac Excel 365 in fourteen locales. [Oracle testing](https://formulon.libraz.net/compatibility/oracle-testing)
|
|
21
|
+
- **Two builds** โ a single-threaded default that loads anywhere, and `@libraz/formulon/threads` for parallel recalculation. [Choosing a build](#choosing-a-build)
|
|
22
|
+
|
|
23
|
+
## Installation
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
npm install @libraz/formulon # browsers and Node 22+
|
|
17
27
|
```
|
|
18
28
|
|
|
19
|
-
|
|
29
|
+
The package is ES modules only and ships its TypeScript declarations.
|
|
20
30
|
|
|
21
31
|
## Quick start
|
|
22
32
|
|
|
@@ -24,192 +34,75 @@ Requires Node.js 22 or newer (the package is shipped as ES modules).
|
|
|
24
34
|
import createFormulon from '@libraz/formulon';
|
|
25
35
|
|
|
26
36
|
const Module = await createFormulon();
|
|
27
|
-
|
|
28
|
-
const r = Module.evalFormula('=SUM(1,2,3)');
|
|
29
|
-
console.log(r.value.number); // 6
|
|
37
|
+
console.log(Module.evalFormula('=SUM(1,2,3)').value.number); // 6
|
|
30
38
|
```
|
|
31
39
|
|
|
32
|
-
|
|
33
|
-
errors (e.g. `#DIV/0!`) are surfaced as a `value.kind === 4` (Error)
|
|
34
|
-
result rather than a failed status; only host-side problems
|
|
35
|
-
(out-of-memory, parser crashes) populate `status.ok === false`.
|
|
40
|
+
Excel errors such as `#DIV/0!` come back as values (`value.kind === 4`); `status.ok === false` is reserved for host-side failures. See [Errors](https://formulon.libraz.net/compatibility/errors).
|
|
36
41
|
|
|
37
|
-
##
|
|
42
|
+
## Recalculate a workbook
|
|
38
43
|
|
|
39
44
|
```js
|
|
40
45
|
import createFormulon from '@libraz/formulon';
|
|
41
46
|
import { readFile, writeFile } from 'node:fs/promises';
|
|
42
47
|
|
|
43
48
|
const Module = await createFormulon();
|
|
44
|
-
|
|
45
|
-
// Load an existing workbook from disk.
|
|
46
|
-
const bytes = await readFile('input.xlsx');
|
|
47
|
-
const wb = Module.Workbook.loadBytes(bytes);
|
|
49
|
+
const wb = Module.Workbook.loadBytes(await readFile('input.xlsx'));
|
|
48
50
|
try {
|
|
49
|
-
if (!wb.isValid())
|
|
50
|
-
throw new Error(`load failed: ${Module.lastErrorMessage()}`);
|
|
51
|
-
}
|
|
51
|
+
if (!wb.isValid()) throw new Error(Module.lastErrorMessage());
|
|
52
52
|
|
|
53
|
-
|
|
54
|
-
wb.
|
|
55
|
-
wb.setFormula(0, 1, 0, '=A1*2'); // Sheet1!A2 = =A1*2
|
|
53
|
+
wb.setNumber(0, 0, 0, 42); // Sheet1!A1
|
|
54
|
+
wb.setFormula(0, 1, 0, '=A1*2'); // Sheet1!A2
|
|
56
55
|
wb.recalc();
|
|
57
|
-
|
|
58
|
-
const a2 = wb.getValue(0, 1, 0);
|
|
59
|
-
console.log(a2.value.number); // 84
|
|
56
|
+
console.log(wb.getValue(0, 1, 0).value.number); // 84
|
|
60
57
|
|
|
61
58
|
const saved = wb.save();
|
|
62
|
-
if (saved.status.ok)
|
|
63
|
-
await writeFile('output.xlsx', saved.bytes);
|
|
64
|
-
}
|
|
59
|
+
if (saved.status.ok) await writeFile('output.xlsx', saved.bytes);
|
|
65
60
|
} finally {
|
|
66
|
-
//
|
|
67
|
-
wb.delete();
|
|
61
|
+
wb.delete(); // workbooks wrap a native handle
|
|
68
62
|
}
|
|
69
63
|
```
|
|
70
64
|
|
|
71
|
-
##
|
|
72
|
-
|
|
73
|
-
The package ships two builds of the same API:
|
|
74
|
-
|
|
75
|
-
| Import | Threads | Hosting requirement |
|
|
76
|
-
| --- | --- | --- |
|
|
77
|
-
| `@libraz/formulon` | none | none; loads in any page, worker, Electron `file://` page, or Node |
|
|
78
|
-
| `@libraz/formulon/threads` | up to 8 Web Workers for `recalcParallel` | a browser page must be cross-origin isolated |
|
|
79
|
-
|
|
80
|
-
The default build uses ordinary (non-shared) memory and starts no workers.
|
|
81
|
-
`recalcParallel` is still callable there and runs the pass serially,
|
|
82
|
-
reporting `workerThreadsStarted: 0`.
|
|
65
|
+
## Switching locale profiles
|
|
83
66
|
|
|
84
|
-
|
|
85
|
-
pre-spawns its worker pool when the factory is called, so in a browser it
|
|
86
|
-
only loads when the page is served with `Cross-Origin-Opener-Policy:
|
|
87
|
-
same-origin` and `Cross-Origin-Embedder-Policy: require-corp`. Node needs
|
|
88
|
-
no extra setup.
|
|
67
|
+
New workbooks use `win-365-en_US`. Formulas are always written with English function names and the stored separators; the profile decides how text is parsed and how results are rendered. Switch it per workbook and recalculate:
|
|
89
68
|
|
|
90
69
|
```js
|
|
91
|
-
|
|
70
|
+
const wb = Module.Workbook.createDefault();
|
|
71
|
+
try {
|
|
72
|
+
wb.setFormula(0, 0, 0, '=LENB("ๆฅๆฌ")'); // A1
|
|
73
|
+
wb.setFormula(0, 1, 0, '=VALUE("1,5")'); // A2
|
|
74
|
+
wb.setFormula(0, 2, 0, '=ISEVEN(2)'); // A3
|
|
75
|
+
|
|
76
|
+
for (const id of ['mac-365-en_US', 'mac-365-ja_JP', 'mac-365-de_DE']) {
|
|
77
|
+
wb.setExcelProfileId(id);
|
|
78
|
+
wb.recalc(); // a profile change marks formulas dirty
|
|
79
|
+
console.log(id, [0, 1, 2].map((row) => wb.getDisplayText(0, row, 0).text));
|
|
80
|
+
}
|
|
81
|
+
} finally {
|
|
82
|
+
wb.delete();
|
|
83
|
+
}
|
|
84
|
+
// mac-365-en_US [ '2', '#VALUE!', 'TRUE' ]
|
|
85
|
+
// mac-365-ja_JP [ '4', '#VALUE!', 'TRUE' ]
|
|
86
|
+
// mac-365-de_DE [ '2', '1,5', 'WAHR' ]
|
|
92
87
|
```
|
|
93
88
|
|
|
94
|
-
|
|
89
|
+
The ids are `{mac,win}-365-{ja_JP,en_US,de_DE,fr_FR,zh_CN,ko_KR,th_TH,es_ES,es_MX,pt_BR,ru_RU,zh_TW,it_IT,nl_NL}`. Every `mac-*` profile and `win-365-ja_JP` is measured against Excel; the other `win-*` profiles are estimated from the Mac measurements. On a `mac-*` profile, text comparison, sorting, lookups and grouping follow that locale's measured Mac Excel collation; `win-*` profiles compare text case-insensitively by bytes, because Windows ordering is not measured. The profile is not saved into the file, so store the id your application targets and apply it again after loading.
|
|
95
90
|
|
|
96
|
-
|
|
97
|
-
(`formulon.wasm`, or `formulon_threads.wasm` for the threads build).
|
|
98
|
-
Consumer-side concerns worth knowing about:
|
|
91
|
+
For a new workbook that matches what Excel creates in a locale, use `Workbook.createForProfile(id)` instead of `createDefault`: it selects the profile and also sets the body and phonetic fonts, the localized Normal style and first sheet names, and the page margins Excel uses there.
|
|
99
92
|
|
|
100
|
-
|
|
101
|
-
spawned by Emscripten with
|
|
102
|
-
`new Worker(new URL("formulon_threads_core.js", import.meta.url), {type: "module"})`.
|
|
103
|
-
Bundlers default to classic (IIFE) workers and must be told otherwise:
|
|
104
|
-
|
|
105
|
-
```ts
|
|
106
|
-
// vite.config.ts
|
|
107
|
-
export default defineConfig({
|
|
108
|
-
worker: { format: 'es' },
|
|
109
|
-
});
|
|
110
|
-
```
|
|
93
|
+
## Choosing a build
|
|
111
94
|
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
**2. Node bridging code is compiled in.** The factory contains a Node
|
|
117
|
-
branch (lazy-loaded `node:module`, plus `node:worker_threads` in the
|
|
118
|
-
threads build) that browser bundlers will warn about as
|
|
119
|
-
"externalised". The warnings are harmless โ the branch is dead code at
|
|
120
|
-
runtime in browsers โ but if you want to silence them, mark the imports
|
|
121
|
-
external:
|
|
122
|
-
|
|
123
|
-
```ts
|
|
124
|
-
// vite.config.ts
|
|
125
|
-
export default defineConfig({
|
|
126
|
-
optimizeDeps: { exclude: ['@libraz/formulon'] },
|
|
127
|
-
build: {
|
|
128
|
-
rollupOptions: {
|
|
129
|
-
external: [/^node:/],
|
|
130
|
-
},
|
|
131
|
-
},
|
|
132
|
-
});
|
|
133
|
-
```
|
|
95
|
+
| Import | Threads | Hosting requirement |
|
|
96
|
+
| --- | --- | --- |
|
|
97
|
+
| `@libraz/formulon` | none; `recalcParallel` runs serially | none; loads in any page, worker, Electron `file://` page, or Node |
|
|
98
|
+
| `@libraz/formulon/threads` | up to 8 workers for `recalcParallel` | a browser page must be cross-origin isolated (COOP / COEP); bundlers need ES module workers |
|
|
134
99
|
|
|
135
|
-
|
|
136
|
-
than just warning, raise the build target to `es2022` so the
|
|
137
|
-
async-function-scoped `await` lexes cleanly:
|
|
100
|
+
Bundler settings for Vite, webpack and esbuild are in [Bundler requirements](https://formulon.libraz.net/runtimes/wasm#bundler-requirements).
|
|
138
101
|
|
|
139
|
-
|
|
140
|
-
// vite.config.ts
|
|
141
|
-
export default defineConfig({
|
|
142
|
-
build: { target: 'es2022' },
|
|
143
|
-
});
|
|
144
|
-
```
|
|
102
|
+
## Non-goals
|
|
145
103
|
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
`Workbook.recalc()` remains the serial, caller-thread recalculation API.
|
|
149
|
-
`Workbook.recalcParallel(threadCount)` starts workers only in the
|
|
150
|
-
`@libraz/formulon/threads` build; it is synchronous and returns a
|
|
151
|
-
`{ status, stats }` result after all workers have joined. A thread count of
|
|
152
|
-
`0` selects automatic detection capped at 8, `1` keeps all evaluation on the
|
|
153
|
-
caller thread and starts no workers, and `2..8` sets the maximum worker count.
|
|
154
|
-
Values above 8 return a failed status with `kInvalidArgument`.
|
|
155
|
-
|
|
156
|
-
The five 64-bit scheduler counters in `stats` are surfaced as JavaScript
|
|
157
|
-
`number` values (not `bigint`) and are exact through `Number.MAX_SAFE_INTEGER`
|
|
158
|
-
(`2^53 - 1`). `workerThreadsStarted` and `workerThreadsUsed` report actual
|
|
159
|
-
worker telemetry; the scheduler may use fewer workers than requested.
|
|
160
|
-
|
|
161
|
-
## API reference
|
|
162
|
-
|
|
163
|
-
The full TypeScript surface is shipped as `dist/formulon.d.ts` and is the
|
|
164
|
-
authoritative reference. Highlights:
|
|
165
|
-
|
|
166
|
-
- `createFormulon(opts?)` -- the default export. Returns a Promise
|
|
167
|
-
resolving to a `FormulonModule`.
|
|
168
|
-
- `Module.evalFormula(formula)` -- one-shot evaluation against a fresh
|
|
169
|
-
workbook.
|
|
170
|
-
- `Module.Workbook.createDefault() / createEmpty() / loadBytes(bytes)` --
|
|
171
|
-
factory methods for building or loading a workbook.
|
|
172
|
-
- `Workbook.setNumber / setBool / setText / setBlank / setFormula` --
|
|
173
|
-
cell mutators.
|
|
174
|
-
- `Workbook.recalc()` -- triggers a serial, full dependency-ordered
|
|
175
|
-
recalculation.
|
|
176
|
-
- `Workbook.recalcParallel(threadCount)` -- synchronously recalculates with
|
|
177
|
-
the parallel SCC scheduler and returns status plus telemetry (serial
|
|
178
|
-
outside the threads build).
|
|
179
|
-
- `Workbook.getValue(sheet, row, col)` -- reads a cached cell value.
|
|
180
|
-
- `Workbook.save()` -- serialises back to an in-memory `.xlsx` byte buffer.
|
|
181
|
-
|
|
182
|
-
Workbook handles wrap a native pointer; always call `wb.delete()` (in a
|
|
183
|
-
`finally` block) when done.
|
|
184
|
-
|
|
185
|
-
Two C ABI capabilities are bound in the Python package but not exposed
|
|
186
|
-
here: `fm_workbook_set_iterative_enabled` (toggling iterative calculation
|
|
187
|
-
without re-supplying the existing iteration cap and residual threshold --
|
|
188
|
-
`setIterative(enabled, maxIterations, maxChange)` here always takes all
|
|
189
|
-
three) and `fm_styles_add_batch` (bulk style registration). This is a
|
|
190
|
-
genuine gap, not an intentional exclusion.
|
|
191
|
-
|
|
192
|
-
## Memory when loading a workbook
|
|
193
|
-
|
|
194
|
-
Both surfaces inflate each worksheet part into memory whole before
|
|
195
|
-
parsing it (the zip reader caps this at 100 MiB per entry, 256 MiB per
|
|
196
|
-
load); `loadBytes` here then always builds a DOM tree from that buffer.
|
|
197
|
-
The native CLI switches to a streaming parser for worksheets past 256
|
|
198
|
-
KiB instead, which skips building the DOM tree -- that implementation
|
|
199
|
-
costs binary size the WASM budget does not have -- but still holds the
|
|
200
|
-
same inflated XML buffer first. Sheets are read one at a time, so the
|
|
201
|
-
peak is per worksheet, and the practical ceiling here is the 32-bit WASM
|
|
202
|
-
address space. Results are identical either way.
|
|
203
|
-
|
|
204
|
-
## Project
|
|
205
|
-
|
|
206
|
-
Documentation โ guides, compatibility notes, and the per-runtime API
|
|
207
|
-
reference โ is at <https://formulon.libraz.net>. Source, design notes,
|
|
208
|
-
and the oracle test suite live at <https://github.com/libraz/formulon>.
|
|
209
|
-
[formulon-cell](https://github.com/libraz/formulon-cell) is a browser
|
|
210
|
-
spreadsheet UI built on this package; it doubles as an integration test
|
|
211
|
-
and a worked example of embedding the engine.
|
|
104
|
+
VBA execution, legacy `.xls`, chart rendering, Power Query / DAX, pivot cache refresh from source data, live external connections, and a spreadsheet UI are permanently out of scope. See [Non-goals](https://formulon.libraz.net/compatibility/non-goals).
|
|
212
105
|
|
|
213
106
|
## License
|
|
214
107
|
|
|
215
|
-
Apache License 2.0
|
|
108
|
+
[Apache License 2.0](./LICENSE). See also [NOTICE](./NOTICE).
|
package/dist/common.js
CHANGED
|
@@ -94,6 +94,7 @@ export const ErrorCode = Object.freeze({
|
|
|
94
94
|
Unknown: 16,
|
|
95
95
|
});
|
|
96
96
|
export const CalcMode = Object.freeze({ Auto: 0, Manual: 1, AutoNoTable: 2 });
|
|
97
|
+
export const CollationStrength = Object.freeze({ Compare: 0, Dynamic: 1, ClassicExact: 2 });
|
|
97
98
|
export const SheetVisibility = Object.freeze({ Visible: 0, Hidden: 1, VeryHidden: 2 });
|
|
98
99
|
export const GeometryMode = Object.freeze({ Display: 0, Print: 1 });
|
|
99
100
|
export const FilterKind = Object.freeze({ None: 0, Values: 1, Custom: 2, Top10: 3, Dynamic: 4, Color: 5, Icon: 6 });
|
|
@@ -195,8 +196,8 @@ export const LogLevel = Object.freeze({ Debug: 0, Info: 1, Warn: 2, Error: 3, Of
|
|
|
195
196
|
* `undefined`/`null` to leave `base` unchanged (signature/description
|
|
196
197
|
* stay `undefined`).
|
|
197
198
|
* @param {string} locale A BCP-47 display locale tag (e.g. `"fr-FR"`),
|
|
198
|
-
* matching the keys in `aliases` / `localized`. Independent of the
|
|
199
|
-
*
|
|
199
|
+
* matching the keys in `aliases` / `localized`. Independent of the profile id
|
|
200
|
+
* passed to the engine locale calls.
|
|
200
201
|
* @returns {object} The merged metadata (a new object), or `base` verbatim
|
|
201
202
|
* when `entry` is absent.
|
|
202
203
|
*/
|