@libraz/formulon 0.11.1 → 0.12.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 +53 -20
- package/dist/common.js +139 -0
- package/dist/formulon.d.ts +128 -76
- package/dist/formulon.js +3 -138
- package/dist/formulon.wasm +0 -0
- package/dist/formulon_core.js +2 -2
- package/dist/formulon_threads.js +10 -0
- package/dist/formulon_threads.wasm +0 -0
- package/dist/formulon_threads_core.js +2 -0
- package/package.json +10 -2
package/README.md
CHANGED
|
@@ -68,14 +68,38 @@ try {
|
|
|
68
68
|
}
|
|
69
69
|
```
|
|
70
70
|
|
|
71
|
+
## Choosing a build
|
|
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`.
|
|
83
|
+
|
|
84
|
+
The threads build allocates its memory as a `SharedArrayBuffer` and
|
|
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.
|
|
89
|
+
|
|
90
|
+
```js
|
|
91
|
+
import createFormulon from '@libraz/formulon/threads';
|
|
92
|
+
```
|
|
93
|
+
|
|
71
94
|
## Bundler integration (Vite, webpack, esbuild)
|
|
72
95
|
|
|
73
|
-
|
|
74
|
-
`formulon.wasm
|
|
96
|
+
Each build is an ES module factory plus a companion `.wasm`
|
|
97
|
+
(`formulon.wasm`, or `formulon_threads.wasm` for the threads build).
|
|
98
|
+
Consumer-side concerns worth knowing about:
|
|
75
99
|
|
|
76
|
-
**1.
|
|
77
|
-
|
|
78
|
-
`new Worker(new URL("
|
|
100
|
+
**1. The threads build needs ES module workers.** Its pthread workers are
|
|
101
|
+
spawned by Emscripten with
|
|
102
|
+
`new Worker(new URL("formulon_threads_core.js", import.meta.url), {type: "module"})`.
|
|
79
103
|
Bundlers default to classic (IIFE) workers and must be told otherwise:
|
|
80
104
|
|
|
81
105
|
```ts
|
|
@@ -90,8 +114,8 @@ webpack 5 picks up the `{type: "module"}` automatically when
|
|
|
90
114
|
chunk.
|
|
91
115
|
|
|
92
116
|
**2. Node bridging code is compiled in.** The factory contains a Node
|
|
93
|
-
branch (lazy-loaded `node:module
|
|
94
|
-
|
|
117
|
+
branch (lazy-loaded `node:module`, plus `node:worker_threads` in the
|
|
118
|
+
threads build) that browser bundlers will warn about as
|
|
95
119
|
"externalised". The warnings are harmless — the branch is dead code at
|
|
96
120
|
runtime in browsers — but if you want to silence them, mark the imports
|
|
97
121
|
external:
|
|
@@ -119,15 +143,11 @@ export default defineConfig({
|
|
|
119
143
|
});
|
|
120
144
|
```
|
|
121
145
|
|
|
122
|
-
**3. Workers + SharedArrayBuffer require cross-origin isolation.** When
|
|
123
|
-
hosting in a browser, serve the page with `Cross-Origin-Opener-Policy:
|
|
124
|
-
same-origin` and `Cross-Origin-Embedder-Policy: require-corp` headers,
|
|
125
|
-
or pthread workers will refuse to start.
|
|
126
|
-
|
|
127
146
|
### Parallel recalculation
|
|
128
147
|
|
|
129
148
|
`Workbook.recalc()` remains the serial, caller-thread recalculation API.
|
|
130
|
-
`Workbook.recalcParallel(threadCount)`
|
|
149
|
+
`Workbook.recalcParallel(threadCount)` starts workers only in the
|
|
150
|
+
`@libraz/formulon/threads` build; it is synchronous and returns a
|
|
131
151
|
`{ status, stats }` result after all workers have joined. A thread count of
|
|
132
152
|
`0` selects automatic detection capped at 8, `1` keeps all evaluation on the
|
|
133
153
|
caller thread and starts no workers, and `2..8` sets the maximum worker count.
|
|
@@ -154,21 +174,31 @@ authoritative reference. Highlights:
|
|
|
154
174
|
- `Workbook.recalc()` -- triggers a serial, full dependency-ordered
|
|
155
175
|
recalculation.
|
|
156
176
|
- `Workbook.recalcParallel(threadCount)` -- synchronously recalculates with
|
|
157
|
-
the parallel SCC scheduler and returns status plus telemetry
|
|
177
|
+
the parallel SCC scheduler and returns status plus telemetry (serial
|
|
178
|
+
outside the threads build).
|
|
158
179
|
- `Workbook.getValue(sheet, row, col)` -- reads a cached cell value.
|
|
159
180
|
- `Workbook.save()` -- serialises back to an in-memory `.xlsx` byte buffer.
|
|
160
181
|
|
|
161
182
|
Workbook handles wrap a native pointer; always call `wb.delete()` (in a
|
|
162
183
|
`finally` block) when done.
|
|
163
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
|
+
|
|
164
192
|
## Memory when loading a workbook
|
|
165
193
|
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
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
|
|
172
202
|
address space. Results are identical either way.
|
|
173
203
|
|
|
174
204
|
## Project
|
|
@@ -176,6 +206,9 @@ address space. Results are identical either way.
|
|
|
176
206
|
Documentation — guides, compatibility notes, and the per-runtime API
|
|
177
207
|
reference — is at <https://formulon.libraz.net>. Source, design notes,
|
|
178
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.
|
|
179
212
|
|
|
180
213
|
## License
|
|
181
214
|
|
package/dist/common.js
ADDED
|
@@ -0,0 +1,139 @@
|
|
|
1
|
+
// Value constants and pure helpers declared in formulon.d.ts, shared by the
|
|
2
|
+
// `@libraz/formulon` and `@libraz/formulon/threads` entry shims.
|
|
3
|
+
|
|
4
|
+
export const ValueKind = Object.freeze({
|
|
5
|
+
Blank: 0,
|
|
6
|
+
Number: 1,
|
|
7
|
+
Bool: 2,
|
|
8
|
+
Text: 3,
|
|
9
|
+
Error: 4,
|
|
10
|
+
Array: 5,
|
|
11
|
+
Ref: 6,
|
|
12
|
+
Lambda: 7,
|
|
13
|
+
});
|
|
14
|
+
export const WorkbookFormat = Object.freeze({ Unknown: 0, Xlsx: 1, Xlsb: 2 });
|
|
15
|
+
export const PivotCellKind = Object.freeze({
|
|
16
|
+
Header: 0,
|
|
17
|
+
RowLabel: 1,
|
|
18
|
+
ColLabel: 2,
|
|
19
|
+
Data: 3,
|
|
20
|
+
RowSubtotal: 4,
|
|
21
|
+
ColSubtotal: 5,
|
|
22
|
+
GrandTotal: 6,
|
|
23
|
+
Blank: 7,
|
|
24
|
+
});
|
|
25
|
+
export const PivotAxis = Object.freeze({ Row: 0, Col: 1, Value: 2, Page: 3 });
|
|
26
|
+
export const PivotAggregation = Object.freeze({
|
|
27
|
+
Sum: 0,
|
|
28
|
+
Count: 1,
|
|
29
|
+
Average: 2,
|
|
30
|
+
Max: 3,
|
|
31
|
+
Min: 4,
|
|
32
|
+
Product: 5,
|
|
33
|
+
CountNumbers: 6,
|
|
34
|
+
StdDev: 7,
|
|
35
|
+
StdDevP: 8,
|
|
36
|
+
Var: 9,
|
|
37
|
+
VarP: 10,
|
|
38
|
+
});
|
|
39
|
+
export const PivotShowValuesAs = Object.freeze({
|
|
40
|
+
Normal: 0,
|
|
41
|
+
PercentOfRow: 1,
|
|
42
|
+
PercentOfCol: 2,
|
|
43
|
+
PercentOfTotal: 3,
|
|
44
|
+
RunningTotalInRow: 4,
|
|
45
|
+
RunningTotalInCol: 5,
|
|
46
|
+
Index: 6,
|
|
47
|
+
DifferenceFrom: 7,
|
|
48
|
+
PercentDifferenceFrom: 8,
|
|
49
|
+
PercentOfParentRow: 9,
|
|
50
|
+
PercentOfParentCol: 10,
|
|
51
|
+
PercentOfParent: 11,
|
|
52
|
+
});
|
|
53
|
+
export const PIVOT_SHOW_AS_BASE_PREVIOUS = 1048828;
|
|
54
|
+
export const PIVOT_SHOW_AS_BASE_NEXT = 1048829;
|
|
55
|
+
export const PivotFilterType = Object.freeze({
|
|
56
|
+
ValueTop10: 0,
|
|
57
|
+
ValueGreaterThan: 1,
|
|
58
|
+
ValueBetween: 2,
|
|
59
|
+
LabelContains: 3,
|
|
60
|
+
LabelBeginsWith: 4,
|
|
61
|
+
LabelDate: 5,
|
|
62
|
+
});
|
|
63
|
+
export const PivotDateGrouping = Object.freeze({
|
|
64
|
+
Day: 0,
|
|
65
|
+
Month: 1,
|
|
66
|
+
Quarter: 2,
|
|
67
|
+
Year: 3,
|
|
68
|
+
Days: 4,
|
|
69
|
+
Hour: 5,
|
|
70
|
+
Minute: 6,
|
|
71
|
+
Second: 7,
|
|
72
|
+
});
|
|
73
|
+
export const PivotCalendar = Object.freeze({ Gregorian: 0, Japanese: 1 });
|
|
74
|
+
export const PivotReportLayout = Object.freeze({ Compact: 0, Tabular: 1, Outline: 2 });
|
|
75
|
+
export const PivotFilterValueKind = Object.freeze({ None: -1, Int: 0, Double: 1, Text: 2 });
|
|
76
|
+
export const CfMatchKind = Object.freeze({ DifferentialFormat: 0, ColorScale: 1, DataBar: 2, IconSet: 3 });
|
|
77
|
+
export const ErrorCode = Object.freeze({
|
|
78
|
+
Null: 0,
|
|
79
|
+
Div0: 1,
|
|
80
|
+
Value: 2,
|
|
81
|
+
Ref: 3,
|
|
82
|
+
Name: 4,
|
|
83
|
+
Num: 5,
|
|
84
|
+
NA: 6,
|
|
85
|
+
GettingData: 7,
|
|
86
|
+
Spill: 8,
|
|
87
|
+
Calc: 9,
|
|
88
|
+
Field: 10,
|
|
89
|
+
Blocked: 11,
|
|
90
|
+
Connect: 12,
|
|
91
|
+
External: 13,
|
|
92
|
+
Busy: 14,
|
|
93
|
+
Python: 15,
|
|
94
|
+
Unknown: 16,
|
|
95
|
+
});
|
|
96
|
+
export const CalcMode = Object.freeze({ Auto: 0, Manual: 1, AutoNoTable: 2 });
|
|
97
|
+
export const SheetVisibility = Object.freeze({ Visible: 0, Hidden: 1, VeryHidden: 2 });
|
|
98
|
+
export const ExternalLinkKind = Object.freeze({ Unknown: 0, ExternalBook: 1, Ole: 2, Dde: 3 });
|
|
99
|
+
export const LogLevel = Object.freeze({ Debug: 0, Info: 1, Warn: 2, Error: 3, Off: 4 });
|
|
100
|
+
|
|
101
|
+
/**
|
|
102
|
+
* Merge a host-supplied metadata entry over the engine's structural
|
|
103
|
+
* `functionMetadata()` result.
|
|
104
|
+
*
|
|
105
|
+
* This is a pure, side-effect-free helper: it does not touch the engine.
|
|
106
|
+
* The engine returns `signatureTemplate` / `description` as
|
|
107
|
+
* `undefined`; a host injects display metadata (see
|
|
108
|
+
* `docs/function-metadata-schema.md`) and merges it here at display time.
|
|
109
|
+
* The metadata is display-only and never affects formula parsing or
|
|
110
|
+
* evaluation.
|
|
111
|
+
*
|
|
112
|
+
* Field precedence (first non-nullish wins):
|
|
113
|
+
* - signatureTemplate: `entry.localized[locale].signature` ->
|
|
114
|
+
* `entry.signature` -> `base.signatureTemplate`
|
|
115
|
+
* - description: `entry.localized[locale].description` ->
|
|
116
|
+
* `entry.description` -> `base.description`
|
|
117
|
+
* - localizedName: `entry.aliases[locale]` -> `base.name`
|
|
118
|
+
*
|
|
119
|
+
* @param {object} base A `FunctionMetadataResult` from `functionMetadata()`.
|
|
120
|
+
* @param {object|undefined} entry The provider's `functions[NAME]` entry, or
|
|
121
|
+
* `undefined`/`null` to leave `base` unchanged (signature/description
|
|
122
|
+
* stay `undefined`).
|
|
123
|
+
* @param {string} locale A BCP-47 display locale tag (e.g. `"fr-FR"`),
|
|
124
|
+
* matching the keys in `aliases` / `localized`. Independent of the numeric
|
|
125
|
+
* locale code passed to `functionMetadata()`.
|
|
126
|
+
* @returns {object} The merged metadata (a new object), or `base` verbatim
|
|
127
|
+
* when `entry` is absent.
|
|
128
|
+
*/
|
|
129
|
+
export function mergeFunctionMetadata(base, entry, locale) {
|
|
130
|
+
if (entry === undefined || entry === null) {
|
|
131
|
+
return base;
|
|
132
|
+
}
|
|
133
|
+
const localized = (entry.localized && entry.localized[locale]) || {};
|
|
134
|
+
const signatureTemplate = localized.signature ?? entry.signature ?? base.signatureTemplate;
|
|
135
|
+
const description = localized.description ?? entry.description ?? base.description;
|
|
136
|
+
const aliasName = entry.aliases && entry.aliases[locale];
|
|
137
|
+
const localizedName = aliasName ?? base.name;
|
|
138
|
+
return { ...base, signatureTemplate, description, localizedName };
|
|
139
|
+
}
|