@libraz/formulon 0.8.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.
@@ -0,0 +1,1385 @@
1
+ // Copyright 2026 libraz. Licensed under the Apache License, Version 2.0.
2
+ //
3
+ // Hand-written TypeScript declarations for the Formulon WASM bindings.
4
+ //
5
+ // The single entry point is the default export from `formulon.js`,
6
+ // which is the Emscripten module factory produced under
7
+ // MODULARIZE=1 / EXPORT_NAME=createFormulon / EXPORT_ES6=1. It returns
8
+ // a Promise resolving to the Module surface declared below.
9
+ //
10
+ // Mirror of `EMSCRIPTEN_BINDINGS(formulon)` in `src/wasm/embind.cpp`.
11
+ // Keep this file in sync when adding or removing bindings.
12
+
13
+ /** `fm_value_kind_t` ordinals (mirror of `fm_value_kind_t`). */
14
+ export enum ValueKind {
15
+ Blank = 0,
16
+ Number = 1,
17
+ Bool = 2,
18
+ Text = 3,
19
+ Error = 4,
20
+ Array = 5,
21
+ Ref = 6,
22
+ Lambda = 7,
23
+ }
24
+
25
+ /** Result envelope returned by every fallible binding call. */
26
+ export interface Status {
27
+ /** True when the underlying C ABI returned `kOk`. */
28
+ ok: boolean;
29
+ /** Numeric `fm_status_t`. 0 on success. */
30
+ status: number;
31
+ /** Thread-local last-error message (empty on success). */
32
+ message: string;
33
+ /** Optional thread-local context string (empty on success). */
34
+ context: string;
35
+ }
36
+
37
+ /** Flattened mirror of `fm_value_t`. Only the field selected by `kind`
38
+ * is meaningful; the others carry default-zero values. */
39
+ export interface Value {
40
+ kind: ValueKind;
41
+ /** Active when `kind === ValueKind.Number`. */
42
+ number: number;
43
+ /** Active when `kind === ValueKind.Bool` (0 or 1). */
44
+ boolean: number;
45
+ /** Active when `kind === ValueKind.Text`. */
46
+ text: string;
47
+ /** Active when `kind === ValueKind.Error`; a `formulon::ErrorCode` ordinal. */
48
+ errorCode: number;
49
+ }
50
+
51
+ /** `{ status, value }` pair returned by cell-read entry points. */
52
+ export interface CellResult {
53
+ status: Status;
54
+ value: Value;
55
+ }
56
+
57
+ /** Return type of `evalFormula(...)`. */
58
+ export interface EvalResult {
59
+ status: Status;
60
+ value: Value;
61
+ }
62
+
63
+ /** Return type of `Workbook.save()`. */
64
+ export interface SaveResult {
65
+ status: Status;
66
+ /** Freshly-allocated `Uint8Array` on success; `null` on failure. */
67
+ bytes: Uint8Array | null;
68
+ }
69
+
70
+ /** Return type of `Workbook.sheetName(idx)`. */
71
+ export interface StringResult {
72
+ status: Status;
73
+ value: string;
74
+ }
75
+
76
+ /** Return type of `Workbook.cellAt(sheet, idx)`. */
77
+ export interface CellEntry {
78
+ status: Status;
79
+ row: number;
80
+ col: number;
81
+ /** Raw formula text, or `null` for pure literals. */
82
+ formula: string | null;
83
+ value: Value;
84
+ }
85
+
86
+ /** Return type of `Workbook.definedNameAt(idx)`. */
87
+ export interface DefinedNameEntry {
88
+ status: Status;
89
+ name: string;
90
+ formula: string;
91
+ }
92
+
93
+ /** Return type of `Workbook.tableAt(idx)`. */
94
+ export interface TableEntry {
95
+ status: Status;
96
+ name: string;
97
+ displayName: string;
98
+ ref: string;
99
+ sheetIndex: number;
100
+ }
101
+
102
+ /** Return type of `Workbook.passthroughAt(idx)`. */
103
+ export interface PassthroughEntry {
104
+ status: Status;
105
+ path: string;
106
+ }
107
+
108
+ /** PivotTable layout cell kind. Mirrors `fm_pivot_cell_kind_t`. */
109
+ export enum PivotCellKind {
110
+ Header = 0,
111
+ RowLabel = 1,
112
+ ColLabel = 2,
113
+ Data = 3,
114
+ RowSubtotal = 4,
115
+ ColSubtotal = 5,
116
+ GrandTotal = 6,
117
+ Blank = 7,
118
+ }
119
+
120
+ /** One concrete cell in a projected PivotTable layout. */
121
+ export interface PivotCell {
122
+ /** Absolute 0-based sheet row. */
123
+ row: number;
124
+ /** Absolute 0-based sheet column. */
125
+ col: number;
126
+ value: Value;
127
+ kind: PivotCellKind;
128
+ /** Header nesting depth; 0 for data cells. */
129
+ depth: number;
130
+ /** Source field name when known. */
131
+ fieldName: string;
132
+ /** Excel number-format code when known. */
133
+ numberFormat: string;
134
+ }
135
+
136
+ /** Return type of `Workbook.pivotLayout(sheet, pivotIndex)`. */
137
+ export interface PivotLayoutResult {
138
+ status: Status;
139
+ /** Absolute 0-based top row of the rectangular pivot layout. */
140
+ top: number;
141
+ /** Absolute 0-based left column of the rectangular pivot layout. */
142
+ left: number;
143
+ /** Rectangular layout row span. */
144
+ rows: number;
145
+ /** Rectangular layout column span. */
146
+ cols: number;
147
+ /** Sparse projected cells in row-major order. */
148
+ cells: ReadonlyArray<PivotCell>;
149
+ }
150
+
151
+ /** PivotTable axis enumeration. Mirrors `fm_pivot_axis_t`. */
152
+ export enum PivotAxis {
153
+ Row = 0,
154
+ Col = 1,
155
+ Value = 2,
156
+ Page = 3,
157
+ }
158
+
159
+ /** Aggregation function for a value-axis field. Mirrors
160
+ * `fm_pivot_aggregation_t`. */
161
+ export enum PivotAggregation {
162
+ Sum = 0,
163
+ Count = 1,
164
+ Average = 2,
165
+ Max = 3,
166
+ Min = 4,
167
+ Product = 5,
168
+ CountNumbers = 6,
169
+ StdDev = 7,
170
+ StdDevP = 8,
171
+ Var = 9,
172
+ VarP = 10,
173
+ }
174
+
175
+ /** Show-values-as derivation applied to a data-field aggregate.
176
+ * Mirrors `fm_pivot_show_as_t`. */
177
+ export enum PivotShowValuesAs {
178
+ Normal = 0,
179
+ PercentOfRow = 1,
180
+ PercentOfCol = 2,
181
+ PercentOfTotal = 3,
182
+ RunningTotalInRow = 4,
183
+ RunningTotalInCol = 5,
184
+ Index = 6,
185
+ DifferenceFrom = 7,
186
+ PercentDifferenceFrom = 8,
187
+ PercentOfParentRow = 9,
188
+ PercentOfParentCol = 10,
189
+ PercentOfParent = 11,
190
+ }
191
+
192
+ /** Sentinel value for `PivotDataFieldSpec.showAsBaseItem` meaning
193
+ * "(previous)". Mirrors the magic value used by Excel's OOXML
194
+ * `<dataField>` element. */
195
+ export const PIVOT_SHOW_AS_BASE_PREVIOUS = 1048828;
196
+ /** Sentinel value for `PivotDataFieldSpec.showAsBaseItem` meaning
197
+ * "(next)". */
198
+ export const PIVOT_SHOW_AS_BASE_NEXT = 1048829;
199
+
200
+ /** Filter type for an active (slicer-applied) filter. Mirrors
201
+ * `fm_pivot_filter_type_t`. */
202
+ export enum PivotFilterType {
203
+ ValueTop10 = 0,
204
+ ValueGreaterThan = 1,
205
+ ValueBetween = 2,
206
+ LabelContains = 3,
207
+ LabelBeginsWith = 4,
208
+ LabelDate = 5,
209
+ }
210
+
211
+ /** Date-grouping granularity. Mirrors `fm_pivot_date_grouping_t`. */
212
+ export enum PivotDateGrouping {
213
+ Day = 0,
214
+ Month = 1,
215
+ Quarter = 2,
216
+ Year = 3,
217
+ Week = 4,
218
+ Hour = 5,
219
+ Minute = 6,
220
+ Second = 7,
221
+ }
222
+
223
+ /** Calendar system used by date grouping. Mirrors
224
+ * `fm_pivot_calendar_t`. */
225
+ export enum PivotCalendar {
226
+ Gregorian = 0,
227
+ Japanese = 1,
228
+ }
229
+
230
+ /** Discriminator for the variant payload carried by a pivot filter
231
+ * spec. `None` (= -1) means the slot is unset (only meaningful for
232
+ * the optional upper-bound payload on range filters). Mirrors
233
+ * `fm_pivot_filter_value_kind_t`. */
234
+ export enum PivotFilterValueKind {
235
+ None = -1,
236
+ Int = 0,
237
+ Double = 1,
238
+ Text = 2,
239
+ }
240
+
241
+ /** Plain-data spec for `Workbook.pivotFieldAdd`. Mirrors
242
+ * `fm_pivot_field_spec_t`. */
243
+ export interface PivotFieldSpec {
244
+ sourceName: string;
245
+ customName?: string;
246
+ axis: PivotAxis;
247
+ subtotalTop?: boolean;
248
+ numberFormat?: string;
249
+ }
250
+
251
+ /** Plain-data spec for `Workbook.pivotDataFieldAdd` /
252
+ * `pivotDataFieldSet`. Mirrors `fm_pivot_data_field_spec_t`. Pass
253
+ * `-1` for `showAsBaseField` / `showAsBaseItem` to mean "unset". */
254
+ export interface PivotDataFieldSpec {
255
+ name: string;
256
+ fieldIndex: number;
257
+ aggregation: PivotAggregation;
258
+ numberFormat?: string;
259
+ showAs?: PivotShowValuesAs;
260
+ showAsBaseField?: number;
261
+ showAsBaseItem?: number;
262
+ }
263
+
264
+ /** Plain-data spec for `Workbook.pivotFilterAdd`. Mirrors
265
+ * `fm_pivot_filter_spec_t`. For non-range filters, `valueKind` must be
266
+ * one of `Int` / `Double` / `Text`; the high-bound payload is honoured
267
+ * only for range filter types (`ValueBetween`, `LabelDate`). */
268
+ export interface PivotFilterSpec {
269
+ axis: PivotAxis;
270
+ fieldName: string;
271
+ type: PivotFilterType;
272
+ valueKind?: PivotFilterValueKind;
273
+ valueInt?: number;
274
+ valueDouble?: number;
275
+ valueText?: string;
276
+ valueHighKind?: PivotFilterValueKind;
277
+ valueHighInt?: number;
278
+ valueHighDouble?: number;
279
+ }
280
+
281
+ /** Conditional-format match kind. Mirrors `formulon::cf::CFMatchKind`. */
282
+ export enum CfMatchKind {
283
+ DifferentialFormat = 0,
284
+ ColorScale = 1,
285
+ DataBar = 2,
286
+ IconSet = 3,
287
+ }
288
+
289
+ /**
290
+ * Workbook-level calc mode (`<calcPr calcMode>`).
291
+ *
292
+ * - `Auto` — recalc on every input change (Excel default).
293
+ * - `Manual` — only recalc when explicitly requested.
294
+ * - `AutoNoTable` — recalc on every change EXCEPT data-table cells.
295
+ *
296
+ * Round-trip metadata only — the engine recalcs all dirty cells
297
+ * regardless of which mode is set.
298
+ */
299
+ export enum CalcMode {
300
+ Auto = 0,
301
+ Manual = 1,
302
+ AutoNoTable = 2,
303
+ }
304
+
305
+ export type ExcelProfileId = "mac-365-ja_JP" | "win-365-ja_JP";
306
+
307
+ /** RGBA colour. Channels are 0-255 (sRGB). */
308
+ export interface CfColor {
309
+ r: number;
310
+ g: number;
311
+ b: number;
312
+ a: number;
313
+ }
314
+
315
+ /** Resolved CF match. Active fields depend on `kind`; the others carry
316
+ * default-zero values. */
317
+ export interface CfMatch {
318
+ kind: CfMatchKind;
319
+ priority: number;
320
+ /** `1` when `dxfId` is meaningful; `0` otherwise. */
321
+ dxfIdEngaged: number;
322
+ dxfId: number;
323
+ /** Active when `kind === ColorScale`. */
324
+ color: CfColor;
325
+ /** Active when `kind === DataBar`. */
326
+ barLengthPct: number;
327
+ barAxisPositionPct: number;
328
+ barIsNegative: number;
329
+ barFill: CfColor;
330
+ barBorderEngaged: number;
331
+ barBorder: CfColor;
332
+ barGradient: number;
333
+ /** Active when `kind === IconSet`; ordinal of `formulon::cf::IconSetName`. */
334
+ iconSetName: number;
335
+ iconIndex: number;
336
+ }
337
+
338
+ /** Iterable handle backing a `std::vector<CfMatch>` on the C++ side.
339
+ * Mirrors how embind surfaces `register_vector<T>`. */
340
+ export interface CfMatchVector {
341
+ size(): number;
342
+ get(index: number): CfMatch;
343
+ delete(): void;
344
+ }
345
+
346
+ /** One cell's CF result inside a viewport-range evaluation. */
347
+ export interface CfCellResult {
348
+ row: number;
349
+ col: number;
350
+ matches: CfMatchVector;
351
+ }
352
+
353
+ /** Iterable handle backing a `std::vector<CfCellResult>`. */
354
+ export interface CfCellVector {
355
+ size(): number;
356
+ get(index: number): CfCellResult;
357
+ delete(): void;
358
+ }
359
+
360
+ /** Return type of `Workbook.evaluateCfRange(...)`. `cells` is sparse:
361
+ * only cells that produced at least one match appear. */
362
+ export interface CfRangeResult {
363
+ status: Status;
364
+ cells: CfCellVector;
365
+ }
366
+
367
+ /** Per-sheet view: zoom (10..400, default 100), frozen-pane row/col
368
+ * counts, and tab-hidden flag (0/1). */
369
+ export interface SheetView {
370
+ zoomScale: number;
371
+ freezeRows: number;
372
+ freezeCols: number;
373
+ /** Boolean stored as 0/1 to match the embind binding's wire shape. */
374
+ tabHidden: number;
375
+ }
376
+
377
+ /** Return type of `Workbook.getSheetView(sheet)`. */
378
+ export interface SheetViewResult {
379
+ status: Status;
380
+ view: SheetView;
381
+ }
382
+
383
+ /**
384
+ * Mirror of OOXML `<sheetProtection>` (ECMA-376 §18.3.1.85).
385
+ *
386
+ * Round-trip metadata only — the engine does not enforce locks at
387
+ * evaluation time. The host UI inspects these flags to mirror Excel's
388
+ * "Protect Sheet" dialog state. Booleans are encoded as `0`/`1` to
389
+ * match the embind wire shape.
390
+ *
391
+ * `enabled` controls whether the `<sheetProtection>` element is
392
+ * emitted at all; setting it to `0` clears the protection block on
393
+ * save.
394
+ */
395
+ export interface SheetProtection {
396
+ enabled: number;
397
+ algorithmName: string;
398
+ hashValue: string;
399
+ saltValue: string;
400
+ spinCount: number;
401
+ legacyPassword: string;
402
+ sheet: number;
403
+ objects: number;
404
+ scenarios: number;
405
+ formatCells: number;
406
+ formatColumns: number;
407
+ formatRows: number;
408
+ insertColumns: number;
409
+ insertRows: number;
410
+ insertHyperlinks: number;
411
+ deleteColumns: number;
412
+ deleteRows: number;
413
+ selectLockedCells: number;
414
+ selectUnlockedCells: number;
415
+ sort: number;
416
+ autoFilter: number;
417
+ pivotTables: number;
418
+ }
419
+
420
+ /** Return type of `Workbook.getSheetProtection(sheet)`. */
421
+ export interface SheetProtectionResult {
422
+ status: Status;
423
+ protection: SheetProtection;
424
+ }
425
+
426
+ /** Per-column-range layout override. Inclusive `[first, last]` columns
427
+ * carry the same width / hidden / outline level. */
428
+ export interface ColumnLayout {
429
+ first: number;
430
+ last: number;
431
+ width: number;
432
+ /** Boolean stored as 0/1. */
433
+ hidden: number;
434
+ outlineLevel: number;
435
+ }
436
+
437
+ /** Iterable handle backing a `std::vector<ColumnLayout>`. */
438
+ export interface ColumnLayoutVector {
439
+ size(): number;
440
+ get(index: number): ColumnLayout;
441
+ delete(): void;
442
+ }
443
+
444
+ /** Return type of `Workbook.getSheetColumns(sheet)`. */
445
+ export interface ColumnsResult {
446
+ status: Status;
447
+ columns: ColumnLayoutVector;
448
+ }
449
+
450
+ /** Per-row layout override. */
451
+ export interface RowLayout {
452
+ row: number;
453
+ height: number;
454
+ /** Boolean stored as 0/1. */
455
+ hidden: number;
456
+ outlineLevel: number;
457
+ }
458
+
459
+ /** Iterable handle backing a `std::vector<RowLayout>`. */
460
+ export interface RowLayoutVector {
461
+ size(): number;
462
+ get(index: number): RowLayout;
463
+ delete(): void;
464
+ }
465
+
466
+ /** Return type of `Workbook.getSheetRowOverrides(sheet)`. */
467
+ export interface RowsResult {
468
+ status: Status;
469
+ rows: RowLayoutVector;
470
+ }
471
+
472
+ /** Inclusive cell rectangle used by `addMerge` / `getMerges`. */
473
+ export interface MergeRange {
474
+ firstRow: number;
475
+ lastRow: number;
476
+ firstCol: number;
477
+ lastCol: number;
478
+ }
479
+
480
+ /** Sheet hyperlink entry as returned by `getHyperlinks(sheet)`. */
481
+ export interface HyperlinkEntry {
482
+ row: number;
483
+ col: number;
484
+ /** Absolute or relative target (URL, email, internal ref, …). */
485
+ target: string;
486
+ /** Display text override (empty when default). */
487
+ display: string;
488
+ /** Tooltip text (empty when none). */
489
+ tooltip: string;
490
+ }
491
+
492
+ /** Cell comment entry returned by `getComment(sheet, row, col)`. */
493
+ export interface CommentEntry {
494
+ author: string;
495
+ text: string;
496
+ }
497
+
498
+ /** One cell-range entry inside a `DataValidationEntry.ranges`. Identical
499
+ * shape to `MergeRange`; declared separately so the data-validation
500
+ * surface can evolve independently of the merge surface. */
501
+ export interface DataValidationRange {
502
+ readonly firstRow: number;
503
+ readonly firstCol: number;
504
+ readonly lastRow: number;
505
+ readonly lastCol: number;
506
+ }
507
+
508
+ /** One sheet `<dataValidation>` block as returned by
509
+ * `getValidations(sheet)`.
510
+ *
511
+ * Field semantics (matches OOXML `dataValidations.xsd`):
512
+ * * `type` — 0 none, 1 whole, 2 decimal, 3 list, 4 date,
513
+ * 5 time, 6 textLength, 7 custom.
514
+ * * `op` — 0 between, 1 notBetween, 2 equal, 3 notEqual,
515
+ * 4 greaterThan, 5 lessThan,
516
+ * 6 greaterThanOrEqual, 7 lessThanOrEqual.
517
+ * * `errorStyle` — 0 stop, 1 warning, 2 information.
518
+ */
519
+ export interface DataValidationEntry {
520
+ readonly ranges: ReadonlyArray<DataValidationRange>;
521
+ readonly type: number;
522
+ readonly op: number;
523
+ readonly errorStyle: number;
524
+ readonly allowBlank: boolean;
525
+ readonly showInputMessage: boolean;
526
+ readonly showErrorMessage: boolean;
527
+ readonly formula1: string;
528
+ readonly formula2: string;
529
+ readonly errorTitle: string;
530
+ readonly errorMessage: string;
531
+ readonly promptTitle: string;
532
+ readonly promptMessage: string;
533
+ }
534
+
535
+ /** Argument shape accepted by `addValidation(sheet, validation)`. Every
536
+ * field except `type` is optional; missing fields default to `0` for
537
+ * the small enum-shaped integers, `false` for booleans, and `""` for
538
+ * strings. `ranges` is required by the model but accepted as missing
539
+ * to allow zero-range rules. */
540
+ export interface DataValidationInput {
541
+ ranges?: ReadonlyArray<DataValidationRange>;
542
+ type: number;
543
+ op?: number;
544
+ errorStyle?: number;
545
+ allowBlank?: boolean;
546
+ showInputMessage?: boolean;
547
+ showErrorMessage?: boolean;
548
+ formula1?: string;
549
+ formula2?: string;
550
+ errorTitle?: string;
551
+ errorMessage?: string;
552
+ promptTitle?: string;
553
+ promptMessage?: string;
554
+ }
555
+
556
+ /** @deprecated Use {@link DataValidationEntry} instead. */
557
+ export type ValidationEntry = DataValidationEntry;
558
+
559
+ /** Workbook-wide cell coordinate used by trace results. `sheet` is the
560
+ * 0-based sheet index. */
561
+ export interface CellNode {
562
+ readonly sheet: number;
563
+ readonly row: number;
564
+ readonly col: number;
565
+ }
566
+
567
+ /** Result envelope for `functionMetadata(name, locale)`.
568
+ *
569
+ * `ok` is `false` when no function matches `name`; the remaining
570
+ * fields are absent. When `ok` is `true`, `name` / `minArity` /
571
+ * `maxArity` are always populated; `signatureTemplate` and
572
+ * `description` are populated only when the locale metadata table
573
+ * has an entry for this function and locale. */
574
+ export interface FunctionMetadataResult {
575
+ readonly ok: boolean;
576
+ readonly name?: string;
577
+ readonly minArity?: number;
578
+ /** `0xFFFFFFFF` (i.e. `4294967295`) denotes an unbounded variadic. */
579
+ readonly maxArity?: number;
580
+ readonly signatureTemplate?: string;
581
+ readonly description?: string;
582
+ }
583
+
584
+ /** Spill region info returned by `spillInfo(sheet, row, col)`. */
585
+ export interface SpillInfo {
586
+ readonly engaged: boolean;
587
+ readonly anchorRow: number;
588
+ readonly anchorCol: number;
589
+ readonly rows: number;
590
+ readonly cols: number;
591
+ }
592
+
593
+ /** One inclusive cell-range entry inside a CF rule's `sqref` union. */
594
+ export interface ConditionalFormatRange {
595
+ readonly firstRow: number;
596
+ readonly firstCol: number;
597
+ readonly lastRow: number;
598
+ readonly lastCol: number;
599
+ }
600
+
601
+ /** One CF rule as returned by `getConditionalFormats(sheet)`.
602
+ *
603
+ * `type` ordinal mirrors `formulon::cf::RuleType`:
604
+ * 0 expression, 1 cellIs, 2 colorScale, 3 dataBar, 4 iconSet,
605
+ * 5 top10, 6 aboveAverage, 7 containsText, 8 notContainsText,
606
+ * 9 beginsWith, 10 endsWith, 11 containsBlanks, 12 notContainsBlanks,
607
+ * 13 containsErrors, 14 notContainsErrors, 15 timePeriod,
608
+ * 16 duplicateValues, 17 uniqueValues.
609
+ *
610
+ * Visual rule kinds (`colorScale` / `dataBar` / `iconSet`) round-trip
611
+ * through the OOXML reader / writer but their visual sub-spec fields
612
+ * are not yet surfaced through this read API; only `id`, `type`,
613
+ * `priority`, `stopIfTrue`, and `sqref` populate for those kinds.
614
+ */
615
+ export interface ConditionalFormatEntry {
616
+ readonly id: string;
617
+ readonly type: number;
618
+ readonly priority: number;
619
+ readonly stopIfTrue: boolean;
620
+ readonly sqref: ReadonlyArray<ConditionalFormatRange>;
621
+ readonly dxfId?: number;
622
+ readonly formula1?: string;
623
+ readonly formula2?: string;
624
+ /** `formulon::cf::CellIsOperator` ordinal: 0 lt, 1 le, 2 eq, 3 ne,
625
+ * 4 ge, 5 gt, 6 between, 7 notBetween. Engaged for `cellIs` rules. */
626
+ readonly op?: number;
627
+ /** Engaged for `top10` rules. */
628
+ readonly rank?: number;
629
+ readonly percent?: boolean;
630
+ readonly bottom?: boolean;
631
+ /** Engaged for `aboveAverage` rules. */
632
+ readonly aboveAverage?: boolean;
633
+ readonly equalAverage?: boolean;
634
+ readonly stdDev?: number;
635
+ /** Engaged for `containsText` / `beginsWith` / `endsWith` /
636
+ * `notContainsText` rules. */
637
+ readonly text?: string;
638
+ /** `formulon::cf::TimePeriod` ordinal. Engaged for `timePeriod` rules. */
639
+ readonly timePeriod?: number;
640
+ }
641
+
642
+ /** Argument shape accepted by `addConditionalFormat(sheet, rule)`.
643
+ *
644
+ * Visual rule kinds (`colorScale` / `dataBar` / `iconSet`) are
645
+ * rejected — their visual sub-specs are not yet creatable through this
646
+ * API. The OOXML reader / writer continue to round-trip those rules
647
+ * verbatim if they were authored elsewhere.
648
+ *
649
+ * When `priority` is missing, zero, or negative, the engine assigns
650
+ * `existing_max + 1`. When `id` is missing or empty, the engine
651
+ * synthesises one. */
652
+ export interface ConditionalFormatInput {
653
+ sqref: ReadonlyArray<ConditionalFormatRange>;
654
+ type: number;
655
+ priority?: number;
656
+ stopIfTrue?: boolean;
657
+ id?: string;
658
+ dxfId?: number;
659
+ formula1?: string;
660
+ formula2?: string;
661
+ op?: number;
662
+ rank?: number;
663
+ percent?: boolean;
664
+ bottom?: boolean;
665
+ aboveAverage?: boolean;
666
+ equalAverage?: boolean;
667
+ stdDev?: number;
668
+ text?: string;
669
+ timePeriod?: number;
670
+ }
671
+
672
+ /** Return type of `Workbook.getCellXfIndex(sheet, row, col)`. */
673
+ export interface CellXfIndexResult {
674
+ status: Status;
675
+ xfIndex: number;
676
+ }
677
+
678
+ /** Return type of `Workbook.getCellXf(xfIndex)`. */
679
+ export interface CellXfResult {
680
+ status: Status;
681
+ fontIndex: number;
682
+ fillIndex: number;
683
+ borderIndex: number;
684
+ numFmtId: number;
685
+ horizontalAlign: number;
686
+ verticalAlign: number;
687
+ wrapText: boolean;
688
+ }
689
+
690
+ /** Plain-data shape of a font record. Mirrors `formulon::io::FontRecord`. */
691
+ export interface FontRecord {
692
+ name: string;
693
+ size: number;
694
+ bold: boolean;
695
+ italic: boolean;
696
+ strike: boolean;
697
+ /** 0=none, 1=single, 2=double, 3=singleAccounting, 4=doubleAccounting. */
698
+ underline: number;
699
+ /** AARRGGBB packed colour. */
700
+ colorArgb: number;
701
+ }
702
+
703
+ /** Plain-data shape of a fill record. Mirrors `formulon::io::FillRecord`. */
704
+ export interface FillRecord {
705
+ /** OOXML pattern ordinal: 0=none, 1=solid, 2..18=standard pattern set. */
706
+ pattern: number;
707
+ /** Foreground AARRGGBB colour. */
708
+ fgArgb: number;
709
+ /** Background AARRGGBB colour. */
710
+ bgArgb: number;
711
+ }
712
+
713
+ /** One side of a `BorderRecord`. */
714
+ export interface BorderSide {
715
+ /** OOXML border-style ordinal: 0=none, 1=thin, ..., 13=slantDashDot. */
716
+ style: number;
717
+ /** AARRGGBB packed colour. */
718
+ colorArgb: number;
719
+ }
720
+
721
+ /** Plain-data shape of a border record. Mirrors `formulon::io::BorderRecord`. */
722
+ export interface BorderRecord {
723
+ left: BorderSide;
724
+ right: BorderSide;
725
+ top: BorderSide;
726
+ bottom: BorderSide;
727
+ diagonal: BorderSide;
728
+ diagonalUp: boolean;
729
+ diagonalDown: boolean;
730
+ }
731
+
732
+ /** Plain-data shape of an `<xf>` record. Mirrors `formulon::io::CellXf`. */
733
+ export interface CellXf {
734
+ fontIndex: number;
735
+ fillIndex: number;
736
+ borderIndex: number;
737
+ numFmtId: number;
738
+ /** 0=general, 1=left, 2=center, 3=right, 4=fill, 5=justify, 6=centerContinuous, 7=distributed. */
739
+ horizontalAlign: number;
740
+ /** 0=top, 1=center, 2=bottom, 3=justify, 4=distributed. */
741
+ verticalAlign: number;
742
+ wrapText: boolean;
743
+ }
744
+
745
+ /** Return type of `Workbook.getFont(fontIndex)`. */
746
+ export interface FontResult extends FontRecord {
747
+ status: Status;
748
+ }
749
+
750
+ /** Return type of `Workbook.getFill(fillIndex)`. */
751
+ export interface FillResult extends FillRecord {
752
+ status: Status;
753
+ }
754
+
755
+ /** Return type of `Workbook.getBorder(borderIndex)`. */
756
+ export interface BorderResult extends BorderRecord {
757
+ status: Status;
758
+ }
759
+
760
+ /** Return type of `Workbook.getNumFmt(numFmtId)`. */
761
+ export interface NumFmtResult {
762
+ status: Status;
763
+ numFmtId: number;
764
+ formatCode: string;
765
+ }
766
+
767
+ /** Return type of `Workbook.getLambdaText(sheet, row, col)`. The
768
+ * rendered text never carries a leading `=` and is suitable for
769
+ * passing back through `setFormula`. `kInvalidArgument` surfaces when
770
+ * the cell is absent or its cached value is not a lambda. */
771
+ export interface LambdaTextResult {
772
+ status: Status;
773
+ /** Excel formula text in `LAMBDA(p1,p2,body)` form. Empty string
774
+ * when `status` is non-OK. */
775
+ text: string;
776
+ }
777
+
778
+ /** External-link kinds. Mirrors
779
+ * `formulon::io::ExternalLinkRecord::Kind`. */
780
+ export const enum ExternalLinkKind {
781
+ Unknown = 0,
782
+ ExternalBook = 1,
783
+ Ole = 2,
784
+ Dde = 3,
785
+ }
786
+
787
+ /** Element type returned by `Workbook.getExternalLinks()`. Mirrors
788
+ * `formulon::io::ExternalLinkRecord`. The body part itself is not
789
+ * exposed (it round-trips through the OOXML passthrough mechanism);
790
+ * this surface only enumerates the cross-workbook references and
791
+ * their resolved target URLs. */
792
+ export interface ExternalLinkRecord {
793
+ /** 1-based document order matching `<externalReferences>` in
794
+ * `xl/workbook.xml`. */
795
+ index: number;
796
+ /** Workbook-rels Id ("rId3" etc.). */
797
+ relId: string;
798
+ /** Resolved package-relative path of the body part (e.g.
799
+ * `xl/externalLinks/externalLink1.xml`). */
800
+ partPath: string;
801
+ /** Remote workbook URL (e.g. `file:///path/book.xlsx`,
802
+ * `https://example/sheet.xlsx`). Empty when the per-link rels file
803
+ * was missing or unparseable. */
804
+ target: string;
805
+ /** Whether the per-link rels relationship was emitted with
806
+ * `TargetMode="External"` (the common case). */
807
+ targetExternal: boolean;
808
+ /** One of `ExternalLinkKind.*`. */
809
+ kind: number;
810
+ }
811
+
812
+ /** Return type of `Workbook.getCellStyle(index)`. Mirrors
813
+ * `formulon::io::CellStyleRecord`. `xfId` indexes into the named-style
814
+ * xf table reachable via `Workbook.getCellStyleXf(...)`. */
815
+ export interface CellStyleResult {
816
+ status: Status;
817
+ /** Display name (e.g. "Normal", "Heading 1", or a user-defined label). */
818
+ name: string;
819
+ /** Index into the `<cellStyleXfs>` table. */
820
+ xfId: number;
821
+ /** OOXML built-in style ordinal (`0..47`), or `0xFFFFFFFF` for custom
822
+ * entries that did not carry a `builtinId` attribute. */
823
+ builtinId: number;
824
+ /** Outline level for built-in heading styles (0 otherwise). */
825
+ iLevel: number;
826
+ hidden: boolean;
827
+ customBuiltin: boolean;
828
+ }
829
+
830
+ /** Return type of `Workbook.addFont/Fill/Border/Xf(...)`. The
831
+ * add-functions deduplicate against existing entries via linear
832
+ * search; `index` is either the matched index or the freshly-appended
833
+ * index. */
834
+ export interface AddStyleResult {
835
+ status: Status;
836
+ index: number;
837
+ }
838
+
839
+ /** Return type of `Workbook.addNumFmt(formatCode)`. The id is either a
840
+ * matched built-in (`0..163`) or a freshly-assigned custom id (`>= 164`). */
841
+ export interface AddNumFmtResult {
842
+ status: Status;
843
+ numFmtId: number;
844
+ }
845
+
846
+ /** Range used by `partialRecalc`. */
847
+ export interface RecalcViewport {
848
+ sheet: number;
849
+ firstRow: number;
850
+ lastRow: number;
851
+ firstCol: number;
852
+ lastCol: number;
853
+ }
854
+
855
+ /** Return type of `Workbook.partialRecalc(viewport)`. */
856
+ export interface PartialRecalcResult {
857
+ status: Status;
858
+ /** Number of cells the engine actually evaluated. */
859
+ recomputed: number;
860
+ }
861
+
862
+ /** Iterative-solver progress callback. Receives the current
863
+ * iteration number, the maximum residual seen, and the configured
864
+ * iteration cap. Returning `false` (or any falsy value) aborts the
865
+ * solve; returning `true` (or `undefined`) continues. */
866
+ export type IterativeProgressCallback = (
867
+ iteration: number,
868
+ maxResidual: number,
869
+ maxIterations: number,
870
+ ) => boolean | undefined | void;
871
+
872
+ /** Workbook handle. Always release with `delete()` when finished. */
873
+ export interface Workbook {
874
+ /** True when the wrapper holds a live native handle. */
875
+ isValid(): boolean;
876
+ /** Releases the native handle. The instance must not be used afterwards. */
877
+ delete(): void;
878
+
879
+ save(): SaveResult;
880
+ addSheet(name: string): Status;
881
+ /** Removes the sheet at `index`. */
882
+ removeSheet(index: number): Status;
883
+ /** Renames the sheet at `index`. */
884
+ renameSheet(index: number, newName: string): Status;
885
+ /** Moves the sheet from `fromIdx` to `toIdx` (post-removal index). */
886
+ moveSheet(fromIdx: number, toIdx: number): Status;
887
+ sheetCount(): number;
888
+ sheetName(idx: number): StringResult;
889
+
890
+ setNumber(sheet: number, row: number, col: number, value: number): Status;
891
+ setBool(sheet: number, row: number, col: number, value: boolean): Status;
892
+ setText(sheet: number, row: number, col: number, text: string): Status;
893
+ setBlank(sheet: number, row: number, col: number): Status;
894
+ setFormula(sheet: number, row: number, col: number, formula: string): Status;
895
+
896
+ getValue(sheet: number, row: number, col: number): CellResult;
897
+
898
+ /** Renders the lambda value stored at `(sheet, row, col)` as Excel
899
+ * formula text. Returns `kInvalidArgument` when the cell is absent
900
+ * or its cached value is not a lambda. */
901
+ getLambdaText(sheet: number, row: number, col: number): LambdaTextResult;
902
+
903
+ recalc(): Status;
904
+ /** Recalculates only cells touched by the supplied viewport. */
905
+ partialRecalc(viewport: RecalcViewport): PartialRecalcResult;
906
+
907
+ setIterative(enabled: boolean, maxIterations: number, maxChange: number): Status;
908
+ /** Installs (or, when passed `null`, clears) a JS callback invoked
909
+ * after each Gauss-Seidel sweep. Only one callback can be active per
910
+ * WASM instance — installing a new one displaces the previous. */
911
+ setIterativeProgress(callback: IterativeProgressCallback | null): Status;
912
+
913
+ /**
914
+ * Workbook-level calc mode (Excel `<calcPr calcMode>` policy).
915
+ *
916
+ * Returns one of `CalcMode` codes. The engine itself does NOT gate
917
+ * evaluation on this value — every `recalc()` call honours all dirty
918
+ * cells. The mode is preserved as round-trip metadata and surfaced
919
+ * here so the UI can mirror Excel's user-visible state.
920
+ */
921
+ calcMode(): CalcMode;
922
+ setCalcMode(mode: CalcMode): Status;
923
+
924
+ /**
925
+ * Full formula-behaviour profile id. Defaults to `win-365-ja_JP`.
926
+ */
927
+ excelProfileId(): ExcelProfileId;
928
+ setExcelProfileId(profileId: ExcelProfileId): Status;
929
+
930
+ /** Inserts `count` rows at `row` on `sheet` and rewrites cross-workbook
931
+ * references to follow the shift. */
932
+ insertRows(sheet: number, row: number, count: number): Status;
933
+ /** Deletes `count` rows starting at `row` on `sheet`. References that
934
+ * fall inside the deleted interval collapse to `#REF!`. */
935
+ deleteRows(sheet: number, row: number, count: number): Status;
936
+ /** Inserts `count` columns at `col` on `sheet`. */
937
+ insertCols(sheet: number, col: number, count: number): Status;
938
+ /** Deletes `count` columns starting at `col` on `sheet`. */
939
+ deleteCols(sheet: number, col: number, count: number): Status;
940
+
941
+ cellCount(sheet: number): number;
942
+ cellAt(sheet: number, idx: number): CellEntry;
943
+
944
+ definedNameCount(): number;
945
+ definedNameAt(idx: number): DefinedNameEntry;
946
+ /** Adds, replaces, or (when `formula` is empty) removes a workbook-
947
+ * scoped defined name. */
948
+ setDefinedName(name: string, formula: string): Status;
949
+
950
+ tableCount(): number;
951
+ tableAt(idx: number): TableEntry;
952
+
953
+ passthroughCount(): number;
954
+ passthroughAt(idx: number): PassthroughEntry;
955
+
956
+ /** Returns the number of PivotTables anchored on `sheet`. */
957
+ pivotCount(sheet: number): number;
958
+ /** Evaluates and projects a PivotTable into concrete grid cells. */
959
+ pivotLayout(sheet: number, pivotIndex: number): PivotLayoutResult;
960
+
961
+ // ---- PivotCache mutation -----------------------------------------------
962
+ /** Returns the number of pivot caches owned by the workbook. */
963
+ pivotCacheCount(): number;
964
+ /** Returns `{ status, index: cacheId }` for the cache at flat
965
+ * index `idx`. */
966
+ pivotCacheIdAt(idx: number): AddStyleResult;
967
+ /** Creates a new empty pivot cache. Pass `0` for `requestedId` to
968
+ * auto-assign. Returns `{ status, index: cacheId }`. */
969
+ pivotCacheCreate(requestedId: number): AddStyleResult;
970
+ /** Removes the pivot cache with id `cacheId`. Fails if any pivot
971
+ * table still references it. */
972
+ pivotCacheRemove(cacheId: number): Status;
973
+
974
+ /** Number of fields on the cache identified by `cacheId`. */
975
+ pivotCacheFieldCount(cacheId: number): number;
976
+ /** Reads the name of the cache field at `fieldIdx`. */
977
+ pivotCacheFieldName(cacheId: number, fieldIdx: number): StringResult;
978
+ /** Appends a new field with the given UTF-8 name to the cache.
979
+ * `index` carries the new field's index. */
980
+ pivotCacheFieldAdd(cacheId: number, name: string): AddStyleResult;
981
+ /** Drops every field (and every record) from the cache. */
982
+ pivotCacheFieldClear(cacheId: number): Status;
983
+
984
+ /** Number of shared items configured on cache field `fieldIdx`. */
985
+ pivotCacheFieldSharedItemCount(cacheId: number, fieldIdx: number): number;
986
+ /** Appends a numeric shared item to cache field `fieldIdx`. */
987
+ pivotCacheFieldAddSharedItemNumber(cacheId: number, fieldIdx: number, value: number): Status;
988
+ /** Appends a text shared item to cache field `fieldIdx`. */
989
+ pivotCacheFieldAddSharedItemText(cacheId: number, fieldIdx: number, value: string): Status;
990
+ /** Appends a boolean shared item to cache field `fieldIdx`. */
991
+ pivotCacheFieldAddSharedItemBool(cacheId: number, fieldIdx: number, value: boolean): Status;
992
+ /** Appends a blank shared item to cache field `fieldIdx`. */
993
+ pivotCacheFieldAddSharedItemBlank(cacheId: number, fieldIdx: number): Status;
994
+ /** Drops every shared item from cache field `fieldIdx`. */
995
+ pivotCacheFieldClearSharedItems(cacheId: number, fieldIdx: number): Status;
996
+
997
+ /** Returns the number of records on the cache. */
998
+ pivotCacheRecordCount(cacheId: number): number;
999
+ /** Appends a new empty record. `index` carries the new record's index. */
1000
+ pivotCacheRecordAdd(cacheId: number): AddStyleResult;
1001
+ /** Drops every record from the cache. */
1002
+ pivotCacheRecordClear(cacheId: number): Status;
1003
+ /** Sets cell `(recordIdx, fieldIdx)` to a numeric value. */
1004
+ pivotCacheRecordSetNumber(cacheId: number, recordIdx: number, fieldIdx: number, value: number): Status;
1005
+ /** Sets cell `(recordIdx, fieldIdx)` to a UTF-8 text value. */
1006
+ pivotCacheRecordSetText(cacheId: number, recordIdx: number, fieldIdx: number, value: string): Status;
1007
+ /** Sets cell `(recordIdx, fieldIdx)` to a boolean value. */
1008
+ pivotCacheRecordSetBool(cacheId: number, recordIdx: number, fieldIdx: number, value: boolean): Status;
1009
+ /** Sets cell `(recordIdx, fieldIdx)` to Blank. */
1010
+ pivotCacheRecordSetBlank(cacheId: number, recordIdx: number, fieldIdx: number): Status;
1011
+ /** Sets cell `(recordIdx, fieldIdx)` to an Excel error value. */
1012
+ pivotCacheRecordSetError(cacheId: number, recordIdx: number, fieldIdx: number, errorCode: number): Status;
1013
+
1014
+ // ---- PivotTable mutation -----------------------------------------------
1015
+ /** Creates a new empty pivot table. Returns `{ status, index: pivotIdx }`. */
1016
+ pivotCreate(sheet: number, name: string, cacheId: number, anchorRow: number, anchorCol: number): AddStyleResult;
1017
+ /** Removes the pivot table at `pivotIdx`. */
1018
+ pivotRemove(sheet: number, pivotIdx: number): Status;
1019
+ /** Renames the pivot table. */
1020
+ pivotSetName(sheet: number, pivotIdx: number, name: string): Status;
1021
+ /** Updates the pivot's anchor cell and span. */
1022
+ pivotSetAnchor(
1023
+ sheet: number,
1024
+ pivotIdx: number,
1025
+ anchorRow: number,
1026
+ anchorCol: number,
1027
+ spanRows: number,
1028
+ spanCols: number,
1029
+ ): Status;
1030
+ /** Toggles the row / column grand total bands on the pivot. */
1031
+ pivotSetGrandTotals(sheet: number, pivotIdx: number, rowsEnabled: boolean, colsEnabled: boolean): Status;
1032
+
1033
+ /** Number of fields configured on the pivot. */
1034
+ pivotFieldCount(sheet: number, pivotIdx: number): number;
1035
+ /** Appends a new field. Returns `{ status, index: fieldIdx }`. */
1036
+ pivotFieldAdd(sheet: number, pivotIdx: number, spec: PivotFieldSpec): AddStyleResult;
1037
+ /** Drops every field from the pivot. */
1038
+ pivotFieldClear(sheet: number, pivotIdx: number): Status;
1039
+ /** Sets the axis of pivot field `fieldIdx`. */
1040
+ pivotFieldSetAxis(sheet: number, pivotIdx: number, fieldIdx: number, axis: PivotAxis): Status;
1041
+ /** Sets the sort directive on pivot field `fieldIdx`. Pass an empty
1042
+ * `byField` to clear the by-field key. */
1043
+ pivotFieldSetSort(
1044
+ sheet: number,
1045
+ pivotIdx: number,
1046
+ fieldIdx: number,
1047
+ ascending: boolean,
1048
+ byField: string,
1049
+ ): Status;
1050
+ /** Sets the `subtotal_top` flag on pivot field `fieldIdx`. */
1051
+ pivotFieldSetSubtotalTop(sheet: number, pivotIdx: number, fieldIdx: number, top: boolean): Status;
1052
+ /** Appends an aggregation to pivot field `fieldIdx`. */
1053
+ pivotFieldAddAggregation(sheet: number, pivotIdx: number, fieldIdx: number, agg: PivotAggregation): Status;
1054
+ /** Drops every aggregation from pivot field `fieldIdx`. */
1055
+ pivotFieldClearAggregations(sheet: number, pivotIdx: number, fieldIdx: number): Status;
1056
+ /** Appends a manual-filter item to pivot field `fieldIdx`. */
1057
+ pivotFieldAddItem(
1058
+ sheet: number,
1059
+ pivotIdx: number,
1060
+ fieldIdx: number,
1061
+ name: string,
1062
+ visible: boolean,
1063
+ ): Status;
1064
+ /** Drops every manual-filter item from pivot field `fieldIdx`. */
1065
+ pivotFieldClearItems(sheet: number, pivotIdx: number, fieldIdx: number): Status;
1066
+ /** Toggles the visibility of item `itemIdx` on field `fieldIdx`. */
1067
+ pivotFieldSetItemVisible(
1068
+ sheet: number,
1069
+ pivotIdx: number,
1070
+ fieldIdx: number,
1071
+ itemIdx: number,
1072
+ visible: boolean,
1073
+ ): Status;
1074
+ /** Appends a subtotal-fn entry to pivot field `fieldIdx`. */
1075
+ pivotFieldAddSubtotalFn(sheet: number, pivotIdx: number, fieldIdx: number, agg: PivotAggregation): Status;
1076
+ /** Drops every subtotal-fn entry from pivot field `fieldIdx`. */
1077
+ pivotFieldClearSubtotalFns(sheet: number, pivotIdx: number, fieldIdx: number): Status;
1078
+ /** Configures date-grouping on pivot field `fieldIdx`. Pass `-1` for
1079
+ * `startYear` / `endYear` to leave the bound unset. */
1080
+ pivotFieldSetDateGroup(
1081
+ sheet: number,
1082
+ pivotIdx: number,
1083
+ fieldIdx: number,
1084
+ granularity: PivotDateGrouping,
1085
+ calendar: PivotCalendar,
1086
+ startYear: number,
1087
+ endYear: number,
1088
+ ): Status;
1089
+ /** Removes the date-grouping config from pivot field `fieldIdx`. */
1090
+ pivotFieldClearDateGroup(sheet: number, pivotIdx: number, fieldIdx: number): Status;
1091
+ /** Sets the OOXML number-format string on pivot field `fieldIdx`.
1092
+ * Pass an empty string to clear. */
1093
+ pivotFieldSetNumberFormat(sheet: number, pivotIdx: number, fieldIdx: number, utf8: string): Status;
1094
+
1095
+ /** Replaces the row-axis field order with `indices`. Each entry must
1096
+ * be `< pivotFieldCount`. Pass an empty array to clear. */
1097
+ pivotSetRowFieldOrder(sheet: number, pivotIdx: number, indices: ReadonlyArray<number>): Status;
1098
+ /** Replaces the column-axis field order. Same contract as rows. */
1099
+ pivotSetColFieldOrder(sheet: number, pivotIdx: number, indices: ReadonlyArray<number>): Status;
1100
+
1101
+ /** Number of `<dataField>` entries on the pivot. */
1102
+ pivotDataFieldCount(sheet: number, pivotIdx: number): number;
1103
+ /** Appends a new data-field entry. */
1104
+ pivotDataFieldAdd(sheet: number, pivotIdx: number, spec: PivotDataFieldSpec): AddStyleResult;
1105
+ /** Drops every data-field entry from the pivot. */
1106
+ pivotDataFieldClear(sheet: number, pivotIdx: number): Status;
1107
+ /** Replaces the data-field entry at `dataFieldIdx` in place. */
1108
+ pivotDataFieldSet(sheet: number, pivotIdx: number, dataFieldIdx: number, spec: PivotDataFieldSpec): Status;
1109
+
1110
+ /** Number of active (slicer-applied) filters on the pivot. */
1111
+ pivotFilterCount(sheet: number, pivotIdx: number): number;
1112
+ /** Appends an active filter. */
1113
+ pivotFilterAdd(sheet: number, pivotIdx: number, spec: PivotFilterSpec): Status;
1114
+ /** Drops every active filter from the pivot. */
1115
+ pivotFilterClear(sheet: number, pivotIdx: number): Status;
1116
+ /** Removes the active filter at `filterIdx`. */
1117
+ pivotFilterRemoveAt(sheet: number, pivotIdx: number, filterIdx: number): Status;
1118
+
1119
+ /** Evaluates every CF block on `sheet` against the inclusive range
1120
+ * `[(firstRow, firstCol), (lastRow, lastCol)]`. Pass `NaN` for
1121
+ * `todaySerial` to disable `TimePeriod` rules. */
1122
+ evaluateCfRange(
1123
+ sheet: number,
1124
+ firstRow: number,
1125
+ firstCol: number,
1126
+ lastRow: number,
1127
+ lastCol: number,
1128
+ todaySerial: number,
1129
+ ): CfRangeResult;
1130
+
1131
+ /** Reads the per-sheet view (zoom, freeze, tab-hidden). */
1132
+ getSheetView(sheet: number): SheetViewResult;
1133
+ /** Sets the sheet zoom percentage (clamped to `[10, 400]`). */
1134
+ setSheetZoom(sheet: number, zoomScale: number): Status;
1135
+ /** Sets the frozen pane in `(rows, cols)`. */
1136
+ setSheetFreeze(sheet: number, freezeRows: number, freezeCols: number): Status;
1137
+ /** Sets the sheet tab's hidden flag. */
1138
+ setSheetTabHidden(sheet: number, hidden: boolean): Status;
1139
+
1140
+ /**
1141
+ * Reads the sheet's `<sheetProtection>` flags. Strings are
1142
+ * deep-copied; the returned object is independent of the
1143
+ * workbook's storage.
1144
+ */
1145
+ getSheetProtection(sheet: number): SheetProtectionResult;
1146
+ /**
1147
+ * Replaces the sheet's `<sheetProtection>` flags wholesale.
1148
+ * Setting `enabled = 0` clears the protection block on save.
1149
+ */
1150
+ setSheetProtection(sheet: number, protection: SheetProtection): Status;
1151
+
1152
+ /** Returns the column-layout overrides on `sheet` in storage order. */
1153
+ getSheetColumns(sheet: number): ColumnsResult;
1154
+ /** Sets / replaces the column width override on `[first, last]`. */
1155
+ setColumnWidth(sheet: number, first: number, last: number, width: number): Status;
1156
+ /** Sets / replaces the column hidden flag on `[first, last]`. */
1157
+ setColumnHidden(sheet: number, first: number, last: number, hidden: boolean): Status;
1158
+ /** Sets / replaces the column outline level on `[first, last]` (clamped to 0..255). */
1159
+ setColumnOutline(sheet: number, first: number, last: number, level: number): Status;
1160
+
1161
+ /** Returns the row-layout overrides on `sheet`. */
1162
+ getSheetRowOverrides(sheet: number): RowsResult;
1163
+ /** Sets / replaces the row height override at `row`. */
1164
+ setRowHeight(sheet: number, row: number, height: number): Status;
1165
+ /** Sets / replaces the row hidden flag at `row`. */
1166
+ setRowHidden(sheet: number, row: number, hidden: boolean): Status;
1167
+ /** Sets / replaces the row outline level at `row` (clamped to 0..255). */
1168
+ setRowOutline(sheet: number, row: number, level: number): Status;
1169
+
1170
+ /** Returns `{ status, xfIndex }` for the cell at `(sheet, row, col)`. */
1171
+ getCellXfIndex(sheet: number, row: number, col: number): CellXfIndexResult;
1172
+ /** Persists `xfIndex` on the cell at `(sheet, row, col)`. */
1173
+ setCellXfIndex(sheet: number, row: number, col: number, xfIndex: number): Status;
1174
+ /** Returns the resolved XF record at `xfIndex`. */
1175
+ getCellXf(xfIndex: number): CellXfResult;
1176
+ /** Returns the resolved font record at `fontIndex`. */
1177
+ getFont(fontIndex: number): FontResult;
1178
+ /** Returns the resolved fill record at `fillIndex`. */
1179
+ getFill(fillIndex: number): FillResult;
1180
+ /** Returns the resolved border record at `borderIndex`. */
1181
+ getBorder(borderIndex: number): BorderResult;
1182
+ /** Returns the format string registered for `numFmtId`. */
1183
+ getNumFmt(numFmtId: number): NumFmtResult;
1184
+
1185
+ /** Adds a font (deduplicating against existing entries) and returns
1186
+ * the resolved index. */
1187
+ addFont(record: FontRecord): AddStyleResult;
1188
+ /** Adds a fill (deduplicating against existing entries). */
1189
+ addFill(record: FillRecord): AddStyleResult;
1190
+ /** Adds a border (deduplicating against existing entries). */
1191
+ addBorder(record: BorderRecord): AddStyleResult;
1192
+ /** Adds a number-format code. Built-in matches return the built-in id
1193
+ * without modifying the table; custom codes are appended at
1194
+ * `max(existing_custom_id, 163) + 1`. */
1195
+ addNumFmt(formatCode: string): AddNumFmtResult;
1196
+ /** Adds an `<xf>` record (deduplicating against existing entries).
1197
+ * Out-of-range font/fill/border indices or unregistered `numFmtId`
1198
+ * surface `kInvalidArgument` rather than auto-growing the parallel
1199
+ * tables. */
1200
+ addXf(record: CellXf): AddStyleResult;
1201
+
1202
+ /** Returns the number of font records currently registered. */
1203
+ fontCount(): number;
1204
+ /** Returns the number of fill records currently registered. */
1205
+ fillCount(): number;
1206
+ /** Returns the number of border records currently registered. */
1207
+ borderCount(): number;
1208
+ /** Returns the number of `<xf>` records currently registered. */
1209
+ xfCount(): number;
1210
+
1211
+ /** Returns the number of named cell styles (`<cellStyle>` entries)
1212
+ * registered. Zero for workbooks that do not declare any named
1213
+ * styles. */
1214
+ cellStyleCount(): number;
1215
+ /** Returns the number of `<cellStyleXfs>` records — the named-style
1216
+ * xf table referenced by `CellStyleResult.xfId`. Independent of the
1217
+ * per-cell `cellXfs` table. */
1218
+ cellStyleXfCount(): number;
1219
+ /** Returns the named cell style at `index`. Out-of-range indices
1220
+ * surface `kInvalidArgument` via `status`. */
1221
+ getCellStyle(index: number): CellStyleResult;
1222
+ /** Returns the named-style xf record at `index`. Output shape mirrors
1223
+ * `getCellXf`. */
1224
+ getCellStyleXf(index: number): CellXfResult;
1225
+
1226
+ /** Returns every external-link record carried by the workbook in
1227
+ * `<externalReferences>` document order. Empty for fresh workbooks
1228
+ * and any package whose source archive had no `<externalReferences>`
1229
+ * block. */
1230
+ getExternalLinks(): ReadonlyArray<ExternalLinkRecord>;
1231
+
1232
+ /** Adds a merge range to `sheet`. */
1233
+ addMerge(sheet: number, range: MergeRange): Status;
1234
+ /** Removes every merge that overlaps `range` (inclusive). No-op when nothing overlaps. */
1235
+ removeMerge(sheet: number, range: MergeRange): Status;
1236
+ /** Removes the merge at `index`. Returns kInvalidArgument if `index` is out of range. */
1237
+ removeMergeAt(sheet: number, index: number): Status;
1238
+ /** Drops every merge on `sheet`. */
1239
+ clearMerges(sheet: number): Status;
1240
+ /** Returns every merge range on `sheet` as a JS array. */
1241
+ getMerges(sheet: number): ReadonlyArray<MergeRange>;
1242
+
1243
+ /** Returns the cell comment at `(sheet, row, col)`, or `null` when absent. */
1244
+ getComment(sheet: number, row: number, col: number): CommentEntry | null;
1245
+ /** Sets / replaces the cell comment. Pass an empty `text` to remove. */
1246
+ setComment(sheet: number, row: number, col: number, author: string, text: string): Status;
1247
+
1248
+ /** Appends a hyperlink to `sheet`. Pass empty strings for `display`
1249
+ * or `tooltip` to mean "use the default" or "no tooltip". The
1250
+ * `location` field is filled implicitly (empty) and the writer mints
1251
+ * a fresh `rId` on save. */
1252
+ addHyperlink(sheet: number, row: number, col: number, target: string, display: string, tooltip: string): Status;
1253
+ /** Removes every hyperlink anchored at `(row, col)`. No-op when none match. */
1254
+ removeHyperlink(sheet: number, row: number, col: number): Status;
1255
+ /** Removes the hyperlink at `index`. Returns kInvalidArgument if `index` is out of range. */
1256
+ removeHyperlinkAt(sheet: number, index: number): Status;
1257
+ /** Drops every hyperlink on `sheet`. */
1258
+ clearHyperlinks(sheet: number): Status;
1259
+ /** Returns every hyperlink on `sheet` as a JS array. */
1260
+ getHyperlinks(sheet: number): ReadonlyArray<HyperlinkEntry>;
1261
+
1262
+ /** Returns every data-validation rule on `sheet` in storage order.
1263
+ * Each rule's `ranges` mirrors the OOXML `<dataValidation sqref=...>`
1264
+ * cell-range list; the rule itself surfaces its raw OOXML payload
1265
+ * (the engine does not yet evaluate validation rules). */
1266
+ getValidations(sheet: number): ReadonlyArray<DataValidationEntry>;
1267
+ /** Appends a data-validation rule to `sheet`. */
1268
+ addValidation(sheet: number, validation: DataValidationInput): Status;
1269
+ /** Removes the validation rule at `index`. Returns `kInvalidArgument`
1270
+ * if `index` is out of range. */
1271
+ removeValidationAt(sheet: number, index: number): Status;
1272
+ /** Drops every validation rule on `sheet`. */
1273
+ clearValidations(sheet: number): Status;
1274
+
1275
+ /** Returns every CF rule on `sheet` in flattened priority order. The
1276
+ * returned entries borrow rule ids from the engine's storage; treat
1277
+ * them as immutable view objects. */
1278
+ getConditionalFormats(sheet: number): ReadonlyArray<ConditionalFormatEntry>;
1279
+ /** Appends a new single-rule `<conditionalFormatting>` block to
1280
+ * `sheet`. Visual rule types (`colorScale` / `dataBar` / `iconSet`)
1281
+ * are rejected with `kInvalidArgument` — those payloads are
1282
+ * preserved on round-trip but not yet creatable here. */
1283
+ addConditionalFormat(sheet: number, rule: ConditionalFormatInput): Status;
1284
+ /** Removes the CF rule at `index` (flattened order). When the
1285
+ * containing block becomes empty it is removed too. */
1286
+ removeConditionalFormatAt(sheet: number, index: number): Status;
1287
+ /** Drops every CF block on `sheet`. */
1288
+ clearConditionalFormats(sheet: number): Status;
1289
+
1290
+ /** Returns the cells that `(sheet, row, col)` directly reads
1291
+ * (1-step precedents) when `depth <= 1`, or every cell reached
1292
+ * within `depth` BFS steps otherwise. `depth` is capped at 32 to
1293
+ * avoid runaway expansion in cyclic graphs. */
1294
+ precedents(sheet: number, row: number, col: number, depth: number): ReadonlyArray<CellNode>;
1295
+ /** Returns the cells that read `(sheet, row, col)` directly
1296
+ * (1-step dependents). Same depth semantics as `precedents`. */
1297
+ dependents(sheet: number, row: number, col: number, depth: number): ReadonlyArray<CellNode>;
1298
+
1299
+ /** Returns metadata for the function `name` (case-insensitive). When
1300
+ * the function is unknown, returns `{ok: false}`. `locale` selects
1301
+ * the catalog locale (`0` = `en-US`, `1` = `ja-JP`); description /
1302
+ * signature fields are populated only when the locale metadata table
1303
+ * has an entry. */
1304
+ functionMetadata(name: string, locale: number): FunctionMetadataResult;
1305
+ /** Returns every registered function's canonical name in ascending
1306
+ * sort order. */
1307
+ functionNames(): ReadonlyArray<string>;
1308
+
1309
+ /** Returns the localized display name for the canonical function
1310
+ * `canonicalName` in `locale`. Returns the canonical name unchanged
1311
+ * when the locale's alias table is empty (currently always for
1312
+ * non-`en-US` locales). Returns the empty string when the canonical
1313
+ * name does not match a registered function. */
1314
+ localizeFunctionName(canonicalName: string, locale: number): string;
1315
+ /** Inverse of `localizeFunctionName`: returns the canonical English
1316
+ * name for the localized function `localizedName`. Falls through to
1317
+ * case-insensitive canonical-name matching when no alias is
1318
+ * registered. Returns the empty string when no function matches. */
1319
+ canonicalizeFunctionName(localizedName: string, locale: number): string;
1320
+
1321
+ /** Returns dynamic-array spill info for `(sheet, row, col)`.
1322
+ * When the cell is part of a spill region (anchor or phantom),
1323
+ * `engaged` is `true` and `(anchorRow, anchorCol)` + `(rows, cols)`
1324
+ * describe the region; the per-cell values are read via `getValue`,
1325
+ * which is already spill-aware. When the cell is not part of any
1326
+ * region, `engaged` is `false` and the other fields are zero. */
1327
+ spillInfo(sheet: number, row: number, col: number): SpillInfo;
1328
+ }
1329
+
1330
+ /** Static factories on the Workbook class. */
1331
+ export interface WorkbookCtor {
1332
+ /** Workbook with a single default sheet (`"Sheet1"`). */
1333
+ createDefault(): Workbook;
1334
+ /** Workbook with no sheets. */
1335
+ createEmpty(): Workbook;
1336
+ /** Loads from an in-memory `.xlsx` byte buffer. The returned wrapper
1337
+ * may be invalid (`!isValid()`) on failure; consult
1338
+ * `lastErrorMessage()` for diagnostics. */
1339
+ loadBytes(bytes: Uint8Array): Workbook;
1340
+ }
1341
+
1342
+ /** Type of the resolved Module returned by the factory. */
1343
+ export interface FormulonModule {
1344
+ Workbook: WorkbookCtor;
1345
+
1346
+ /** Convenience: evaluates a single formula in a fresh workbook
1347
+ * (place at `Sheet1!A1`, recalc, return the cached value). */
1348
+ evalFormula(formula: string): EvalResult;
1349
+
1350
+ /** Library version string (UTF-8). */
1351
+ versionString(): string;
1352
+
1353
+ /** Static description of `status` (e.g. `"kOk"`). */
1354
+ statusString(status: number): string;
1355
+
1356
+ /** Most-recent thread-local error message. */
1357
+ lastErrorMessage(): string;
1358
+
1359
+ /** Most-recent thread-local error context. */
1360
+ lastErrorContext(): string;
1361
+ }
1362
+
1363
+ /** Optional Emscripten module-init overrides. Pass to the factory to
1364
+ * customise the default heap, stdout/stderr forwarding, or wasm
1365
+ * binary resolution. */
1366
+ export interface FormulonModuleOptions {
1367
+ locateFile?: (path: string, prefix: string) => string;
1368
+ print?: (msg: string) => void;
1369
+ printErr?: (msg: string) => void;
1370
+ noInitialRun?: boolean;
1371
+ noExitRuntime?: boolean;
1372
+ }
1373
+
1374
+ /**
1375
+ * Default export from `formulon.js`: the Emscripten module factory.
1376
+ *
1377
+ * Usage (Node, ESM):
1378
+ * ```ts
1379
+ * import createFormulon from '@libraz/formulon';
1380
+ * const Module = await createFormulon();
1381
+ * const r = Module.evalFormula('=SUM(1,2,3)');
1382
+ * console.log(r.value.number); // 6
1383
+ * ```
1384
+ */
1385
+ export default function createFormulon(opts?: FormulonModuleOptions): Promise<FormulonModule>;