@libraz/formulon 0.11.0 → 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 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
- The package ships a single ES module factory plus the companion
74
- `formulon.wasm`. Two consumer-side concerns are worth knowing about:
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. `recalcParallel` requires ES module workers.** The parallel recalc
77
- scheduler runs on Web Workers spawned by Emscripten with
78
- `new Worker(new URL("formulon.js", import.meta.url), {type: "module"})`.
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` / `node:worker_threads` for Node
94
- runtime support) that browser bundlers will warn about as
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)` is synchronous and returns a
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
- `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
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
+ }