@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.
@@ -1,10 +1,11 @@
1
1
  //
2
2
  // Hand-written TypeScript declarations for the Formulon WASM bindings.
3
3
  //
4
- // The single entry point is the default export from `formulon.js`,
5
- // which is the Emscripten module factory produced under
6
- // MODULARIZE=1 / EXPORT_NAME=createFormulon / EXPORT_ES6=1. It returns
7
- // a Promise resolving to the Module surface declared below.
4
+ // The entry point is the default export of `@libraz/formulon` (single-
5
+ // threaded) or `@libraz/formulon/threads` (pthread); both are the
6
+ // Emscripten module factory produced under MODULARIZE=1 /
7
+ // EXPORT_NAME=createFormulon / EXPORT_ES6=1 and share this surface. It
8
+ // returns a Promise resolving to the Module surface declared below.
8
9
  //
9
10
  // Mirror of `EMSCRIPTEN_BINDINGS(formulon)` in `src/wasm/embind.cpp`.
10
11
  // Keep this file in sync when adding or removing bindings.
@@ -165,10 +166,20 @@ export enum WorkbookFormat {
165
166
  Xlsb = 2,
166
167
  }
167
168
 
168
- /** Return type of `Workbook.sheetName(idx)`. */
169
- export interface StringResult {
169
+ /** `{ status, value }` returned by the text accessors (`sheetName`,
170
+ * `localizeFunctionName`, `excelProfileId`, ...). `value` is `""` on
171
+ * failure. */
172
+ export interface StringResult<T extends string = string> {
170
173
  status: Status;
171
- value: string;
174
+ value: T;
175
+ }
176
+
177
+ /** `{ status, value }` returned by the numeric accessors (every `*Count`,
178
+ * `calcMode`, ...). `value` is `0` on failure, so a zero count is only
179
+ * meaningful when `status.ok` is true. */
180
+ export interface NumberResult<T extends number = number> {
181
+ status: Status;
182
+ value: T;
172
183
  }
173
184
 
174
185
  /** Return type of `Workbook.cellAt(sheet, idx)`. */
@@ -255,7 +266,7 @@ export interface PivotCell {
255
266
  depth: number;
256
267
  /** Source field name when known. */
257
268
  fieldName: string;
258
- /** Excel number-format code when known. */
269
+ /** The data field's `numFmtId` as a decimal string; empty when unset. */
259
270
  numberFormat: string;
260
271
  }
261
272
 
@@ -334,13 +345,16 @@ export enum PivotFilterType {
334
345
  LabelDate = 5,
335
346
  }
336
347
 
337
- /** Date-grouping granularity. Mirrors `fm_pivot_date_grouping_t`. */
348
+ /** Date-grouping granularity. Mirrors `fm_pivot_date_grouping_t`.
349
+ * `Days` is Excel's "By: Days" grouping (an explicit interval, e.g. a
350
+ * real Excel "week" is `Days` with `intervalDays: 7`); there is no
351
+ * separate week granularity. */
338
352
  export enum PivotDateGrouping {
339
353
  Day = 0,
340
354
  Month = 1,
341
355
  Quarter = 2,
342
356
  Year = 3,
343
- Week = 4,
357
+ Days = 4,
344
358
  Hour = 5,
345
359
  Minute = 6,
346
360
  Second = 7,
@@ -398,6 +412,7 @@ export interface PivotFieldSpec {
398
412
  customName?: string;
399
413
  axis: PivotAxis;
400
414
  subtotalTop?: boolean;
415
+ /** `numFmtId` as a decimal string (built-in or from `addNumFmt`). */
401
416
  numberFormat?: string;
402
417
  }
403
418
 
@@ -408,6 +423,7 @@ export interface PivotDataFieldSpec {
408
423
  name: string;
409
424
  fieldIndex: number;
410
425
  aggregation: PivotAggregation;
426
+ /** `numFmtId` as a decimal string (built-in or from `addNumFmt`). */
411
427
  numberFormat?: string;
412
428
  showAs?: PivotShowValuesAs;
413
429
  showAsBaseField?: number;
@@ -519,6 +535,13 @@ export interface CivilTime {
519
535
  second: number;
520
536
  }
521
537
 
538
+ /** Return type of `Workbook.pinnedNow()`. `now` is `null` when the workbook
539
+ * follows the host clock, and on failure. */
540
+ export interface PinnedNowResult {
541
+ status: Status;
542
+ now: CivilTime | null;
543
+ }
544
+
522
545
  /** RGBA colour. Channels are 0-255 (sRGB). */
523
546
  export interface CfColor {
524
547
  r: number;
@@ -554,6 +577,9 @@ export interface CfMatch {
554
577
  barBorderEngaged: number;
555
578
  barBorder: CfColor;
556
579
  barGradient: number;
580
+ /** The rule's direction (0 = context, 1 = left to right, 2 = right to
581
+ * left); the bar geometry is stated from the left edge. */
582
+ barDirection: number;
557
583
  /** Active when `kind === IconSet`; ordinal of `formulon::cf::IconSetName`. */
558
584
  iconSetName: number;
559
585
  iconIndex: number;
@@ -919,8 +945,10 @@ export function mergeFunctionMetadata(
919
945
  /** Signature of {@link mergeFunctionMetadata}. */
920
946
  export type MergeFunctionMetadata = typeof mergeFunctionMetadata;
921
947
 
922
- /** Spill region info returned by `spillInfo(sheet, row, col)`. */
948
+ /** Spill region info returned by `spillInfo(sheet, row, col)`. On failure
949
+ * `engaged` is `false` and the other fields are zero. */
923
950
  export interface SpillInfo {
951
+ readonly status: Status;
924
952
  readonly engaged: boolean;
925
953
  readonly anchorRow: number;
926
954
  readonly anchorCol: number;
@@ -1002,6 +1030,9 @@ export interface ConditionalFormatEntry {
1002
1030
  readonly border?: CfColor;
1003
1031
  readonly negativeBorder?: CfColor;
1004
1032
  readonly axisColor?: CfColor;
1033
+ /** Edge the bar grows from: 0 = context (the sheet's reading
1034
+ * direction), 1 = left to right, 2 = right to left. */
1035
+ readonly direction: number;
1005
1036
  };
1006
1037
  /** Engaged for `iconSet` rules. */
1007
1038
  readonly iconSet?: {
@@ -1013,6 +1044,9 @@ export interface ConditionalFormatEntry {
1013
1044
  * and save but never consulted during evaluation. Each threshold
1014
1045
  * carries its own `type`, and that type is what interprets it. */
1015
1046
  readonly percent: boolean;
1047
+ /** Lower bound of the lowest icon's bucket; a cell below it gets no
1048
+ * icon. Always present on a rule read back from a workbook. */
1049
+ readonly floor?: CfValueObjectInput;
1016
1050
  };
1017
1051
  }
1018
1052
 
@@ -1064,6 +1098,8 @@ export interface ConditionalFormatInput {
1064
1098
  border?: CfColor;
1065
1099
  negativeBorder?: CfColor;
1066
1100
  axisColor?: CfColor;
1101
+ /** 0 = context (default), 1 = left to right, 2 = right to left. */
1102
+ direction?: number;
1067
1103
  };
1068
1104
  /** Payload for type 4 (`iconSet`). `name` is `formulon::cf::IconSetName` ordinal. */
1069
1105
  iconSet?: {
@@ -1075,6 +1111,9 @@ export interface ConditionalFormatInput {
1075
1111
  * consulted during evaluation (each threshold's own `type` is
1076
1112
  * authoritative). */
1077
1113
  percent?: boolean;
1114
+ /** Lower bound of the lowest icon's bucket; a cell below it gets no
1115
+ * icon. Omit for Excel's default, `percent 0`. */
1116
+ floor?: CfValueObjectInput;
1078
1117
  };
1079
1118
  }
1080
1119
 
@@ -1617,7 +1656,10 @@ export type IterativeProgressCallback = (
1617
1656
  export interface Workbook {
1618
1657
  /** True when the wrapper holds a live native handle. */
1619
1658
  isValid(): boolean;
1620
- /** Releases the native handle. The instance must not be used afterwards. */
1659
+ /** Releases the native handle. The instance must not be used afterwards.
1660
+ * Throws, and leaves the handle intact, if called from inside this
1661
+ * workbook's own iterative-progress callback -- that callback is still
1662
+ * running a `recalc`/`recalcParallel` against the handle. */
1621
1663
  delete(): void;
1622
1664
 
1623
1665
  save(): SaveResult;
@@ -1634,12 +1676,15 @@ export interface Workbook {
1634
1676
  renameSheet(index: number, newName: string): Status;
1635
1677
  /** Moves the sheet from `fromIdx` to `toIdx` (post-removal index). */
1636
1678
  moveSheet(fromIdx: number, toIdx: number): Status;
1637
- sheetCount(): number;
1679
+ sheetCount(): NumberResult;
1638
1680
  sheetName(idx: number): StringResult;
1639
1681
 
1640
1682
  setNumber(sheet: number, row: number, col: number, value: number): Status;
1641
1683
  setBool(sheet: number, row: number, col: number, value: boolean): Status;
1642
- /** Stores a static Excel error literal; `errorCode` is an ErrorCode ordinal. */
1684
+ /** Stores a static Excel error literal; `errorCode` is an ErrorCode
1685
+ * ordinal. Unlike `setNumber`/`setBool`/`setText`, an omitted
1686
+ * `errorCode` has no sane zero-value default, so it is rejected
1687
+ * rather than silently writing error code 0 (`#NULL!`). */
1643
1688
  setError(sheet: number, row: number, col: number, errorCode: number): Status;
1644
1689
  setText(sheet: number, row: number, col: number, text: string): Status;
1645
1690
  /** Stores (or, when empty, clears) the cell's OOXML phonetic guide (`<rPh>`). */
@@ -1664,8 +1709,8 @@ export interface Workbook {
1664
1709
  * single scalar result, without mutating the workbook. Local and
1665
1710
  * cross-sheet references, defined names, and `ROW()` / `COLUMN()` resolve
1666
1711
  * relative to the anchor. An array / spill result is reduced to its
1667
- * top-left element (a pragmatic API shape, not Excel implicit
1668
- * intersection or spilling; multi-cell results are a Phase 2 follow-up).
1712
+ * top-left element (not Excel implicit intersection or spilling; use
1713
+ * `evaluateFormulaArray` for the whole multi-cell result).
1669
1714
  * Note: a self-reference reads the target cell's cached value rather than
1670
1715
  * raising `#REF!`, since the ad-hoc formula never joins the dep graph. */
1671
1716
  evaluateFormulaText(sheet: number, row: number, col: number, formula: string): EvalResult;
@@ -1723,6 +1768,9 @@ export interface Workbook {
1723
1768
  * through `Number.MAX_SAFE_INTEGER` (2^53 - 1).
1724
1769
  * As with `recalc`, a throwing `IterativeProgressCallback` is reported as
1725
1770
  * status 7003 with the counters left at zero.
1771
+ * Only `@libraz/formulon/threads` starts workers. The default
1772
+ * `@libraz/formulon` build has no pthreads, so the same pass runs
1773
+ * serially with `workerThreadsStarted` at 0.
1726
1774
  */
1727
1775
  recalcParallel(threadCount: number): ParallelRecalcResult;
1728
1776
  /** Recalculates only cells touched by the supplied viewport. Reports
@@ -1748,17 +1796,17 @@ export interface Workbook {
1748
1796
  /**
1749
1797
  * Workbook-level calc mode (Excel `<calcPr calcMode>` policy).
1750
1798
  *
1751
- * Returns one of `CalcMode` codes. The engine itself does NOT gate
1799
+ * `value` is one of the `CalcMode` codes. The engine itself does NOT gate
1752
1800
  * evaluation on this value — every `recalc()` call honours all dirty
1753
1801
  * cells. The mode is preserved as round-trip metadata and surfaced
1754
1802
  * here so the UI can mirror Excel's user-visible state.
1755
1803
  */
1756
- calcMode(): CalcMode;
1804
+ calcMode(): NumberResult<CalcMode>;
1757
1805
  setCalcMode(mode: CalcMode): Status;
1758
1806
 
1759
1807
  /**
1760
- * The workbook's pinned wall-clock reading, or `null` when it follows the
1761
- * host clock (the default).
1808
+ * The workbook's pinned wall-clock reading as `now`, or `now: null` when
1809
+ * it follows the host clock (the default).
1762
1810
  *
1763
1811
  * Pinning gives `NOW()`, `TODAY()` and the pivot relative-period filters
1764
1812
  * ("this month", "year to date", ...) one instant to agree on. Without a
@@ -1780,36 +1828,29 @@ export interface Workbook {
1780
1828
  * pin is a calendar instant, not a normalising constructor: a month of 13
1781
1829
  * is rejected rather than rolled into the next year.
1782
1830
  */
1783
- pinnedNow(): CivilTime | null;
1831
+ pinnedNow(): PinnedNowResult;
1784
1832
  setPinnedNow(year: number, month: number, day: number, hour: number, minute: number, second: number): Status;
1785
1833
  clearPinnedNow(): Status;
1786
1834
 
1787
1835
  /**
1788
1836
  * Full formula-behaviour profile id. Defaults to `win-365-ja_JP`.
1789
1837
  */
1790
- excelProfileId(): ExcelProfileId;
1838
+ excelProfileId(): StringResult<ExcelProfileId>;
1791
1839
  setExcelProfileId(profileId: ExcelProfileId): Status;
1792
1840
 
1793
1841
  /**
1794
1842
  * The four structural edits move every structure the engine models:
1795
1843
  * cells, formulas, merges, conditional-format ranges, validations,
1796
1844
  * hyperlinks, tables, print areas, manual breaks and the auto-filter
1797
- * range.
1798
- *
1799
- * They do not move coordinates held in worksheet content the engine
1800
- * keeps byte-verbatim because it does not model it — the worksheet
1801
- * `<extLst>` (the `x14` conditional-formatting block behind DataBar
1802
- * negative-fill / axis / gradient settings, sparkline groups, slicer
1803
- * anchors) and any unmodelled `<worksheet>` child kept so a save does
1804
- * not drop it. Those keep their pre-edit rectangles.
1845
+ * range. The ranges and formulas inside the worksheet `<extLst>` (the
1846
+ * `x14` conditional-formatting block, sparkline groups, `x14`
1847
+ * validations) move with them, as Excel moves them.
1805
1848
  *
1806
- * What that looks like in Excel differs per extension: it drops an
1807
- * `x14` entry whose range no longer matches the legacy rule it extends,
1808
- * so an extended DataBar quietly reverts to its legacy rendering, while
1809
- * a sparkline group keeps drawing and reads its source range from the
1810
- * wrong cells. Neither raises a status or a diagnostic counter. Re-author
1811
- * those extensions after editing rows or columns on a sheet that carries
1812
- * them.
1849
+ * They do not move an unmodelled `<worksheet>` child kept byte-verbatim
1850
+ * so a save does not drop it (a `<sortState>`, for one): a `ref` inside
1851
+ * it keeps its pre-edit rectangle, and nothing reports it. An insert also
1852
+ * does not copy the formatting of the row or column before it onto the
1853
+ * new one, which Excel does — a sparkline included.
1813
1854
  */
1814
1855
 
1815
1856
  /** Inserts `count` rows at `row` on `sheet` and rewrites cross-workbook
@@ -1823,10 +1864,10 @@ export interface Workbook {
1823
1864
  /** Deletes `count` columns starting at `col` on `sheet`. */
1824
1865
  deleteCols(sheet: number, col: number, count: number): Status;
1825
1866
 
1826
- cellCount(sheet: number): number;
1867
+ cellCount(sheet: number): NumberResult;
1827
1868
  cellAt(sheet: number, idx: number): CellEntry;
1828
1869
 
1829
- definedNameCount(): number;
1870
+ definedNameCount(): NumberResult;
1830
1871
  definedNameAt(idx: number): DefinedNameEntry;
1831
1872
  /** Adds, replaces, or (when `formula` is empty) removes a workbook-
1832
1873
  * scoped defined name. */
@@ -1835,7 +1876,7 @@ export interface Workbook {
1835
1876
  * or a sheet-local scope (0-based sheet index). */
1836
1877
  setDefinedNameScoped(name: string, formula: string, localSheetId: number): Status;
1837
1878
 
1838
- tableCount(): number;
1879
+ tableCount(): NumberResult;
1839
1880
  tableAt(idx: number): TableEntry;
1840
1881
  createTable(input: TableInput): AddStyleResult;
1841
1882
  /** Partially updates a table. Omitted fields preserve their current
@@ -1849,17 +1890,17 @@ export interface Workbook {
1849
1890
  /** Replaces the worksheet-level `<autoFilter>` XML fragment; empty clears it. */
1850
1891
  setSheetAutoFilterXml(sheet: number, xml: string): Status;
1851
1892
 
1852
- passthroughCount(): number;
1893
+ passthroughCount(): NumberResult;
1853
1894
  passthroughAt(idx: number): PassthroughEntry;
1854
1895
 
1855
1896
  /** Returns the number of PivotTables anchored on `sheet`. */
1856
- pivotCount(sheet: number): number;
1897
+ pivotCount(sheet: number): NumberResult;
1857
1898
  /** Evaluates and projects a PivotTable into concrete grid cells. */
1858
1899
  pivotLayout(sheet: number, pivotIndex: number): PivotLayoutResult;
1859
1900
 
1860
1901
  // ---- PivotCache mutation -----------------------------------------------
1861
1902
  /** Returns the number of pivot caches owned by the workbook. */
1862
- pivotCacheCount(): number;
1903
+ pivotCacheCount(): NumberResult;
1863
1904
  /** Returns `{ status, index: cacheId }` for the cache at flat
1864
1905
  * index `idx`. */
1865
1906
  pivotCacheIdAt(idx: number): AddStyleResult;
@@ -1875,7 +1916,7 @@ export interface Workbook {
1875
1916
  pivotCacheSetWorksheetSource(cacheId: number, source: PivotWorksheetSource): Status;
1876
1917
 
1877
1918
  /** Number of fields on the cache identified by `cacheId`. */
1878
- pivotCacheFieldCount(cacheId: number): number;
1919
+ pivotCacheFieldCount(cacheId: number): NumberResult;
1879
1920
  /** Reads the name of the cache field at `fieldIdx`. */
1880
1921
  pivotCacheFieldName(cacheId: number, fieldIdx: number): StringResult;
1881
1922
  /** Appends a new field with the given UTF-8 name to the cache.
@@ -1885,7 +1926,7 @@ export interface Workbook {
1885
1926
  pivotCacheFieldClear(cacheId: number): Status;
1886
1927
 
1887
1928
  /** Number of shared items configured on cache field `fieldIdx`. */
1888
- pivotCacheFieldSharedItemCount(cacheId: number, fieldIdx: number): number;
1929
+ pivotCacheFieldSharedItemCount(cacheId: number, fieldIdx: number): NumberResult;
1889
1930
  /** Appends a numeric shared item to cache field `fieldIdx`. */
1890
1931
  pivotCacheFieldAddSharedItemNumber(cacheId: number, fieldIdx: number, value: number): Status;
1891
1932
  /** Appends a text shared item to cache field `fieldIdx`. */
@@ -1900,7 +1941,7 @@ export interface Workbook {
1900
1941
  pivotCacheFieldClearSharedItems(cacheId: number, fieldIdx: number): Status;
1901
1942
 
1902
1943
  /** Returns the number of records on the cache. */
1903
- pivotCacheRecordCount(cacheId: number): number;
1944
+ pivotCacheRecordCount(cacheId: number): NumberResult;
1904
1945
  /** Appends a new empty record. `index` carries the new record's index. */
1905
1946
  pivotCacheRecordAdd(cacheId: number): AddStyleResult;
1906
1947
  /** Drops every record from the cache. */
@@ -1940,7 +1981,7 @@ export interface Workbook {
1940
1981
  pivotSetLayout(sheet: number, pivotIdx: number, layout: PivotReportLayout): Status;
1941
1982
 
1942
1983
  /** Number of fields configured on the pivot. */
1943
- pivotFieldCount(sheet: number, pivotIdx: number): number;
1984
+ pivotFieldCount(sheet: number, pivotIdx: number): NumberResult;
1944
1985
  /** Appends a new field. Returns `{ status, index: fieldIdx }`. */
1945
1986
  pivotFieldAdd(sheet: number, pivotIdx: number, spec: PivotFieldSpec): AddStyleResult;
1946
1987
  /** Drops every field from the pivot. */
@@ -1952,10 +1993,6 @@ export interface Workbook {
1952
1993
  pivotFieldSetSort(sheet: number, pivotIdx: number, fieldIdx: number, ascending: boolean, byField: string): Status;
1953
1994
  /** Sets the `subtotal_top` flag on pivot field `fieldIdx`. */
1954
1995
  pivotFieldSetSubtotalTop(sheet: number, pivotIdx: number, fieldIdx: number, top: boolean): Status;
1955
- /** Appends an aggregation to pivot field `fieldIdx`. */
1956
- pivotFieldAddAggregation(sheet: number, pivotIdx: number, fieldIdx: number, agg: PivotAggregation): Status;
1957
- /** Drops every aggregation from pivot field `fieldIdx`. */
1958
- pivotFieldClearAggregations(sheet: number, pivotIdx: number, fieldIdx: number): Status;
1959
1996
  /** Appends a manual-filter item to pivot field `fieldIdx`, addressed by
1960
1997
  * its label. The item carries no cache binding, so the filter engine
1961
1998
  * matches source records by comparing their rendered label against
@@ -1985,7 +2022,15 @@ export interface Workbook {
1985
2022
  /** Drops every subtotal-fn entry from pivot field `fieldIdx`. */
1986
2023
  pivotFieldClearSubtotalFns(sheet: number, pivotIdx: number, fieldIdx: number): Status;
1987
2024
  /** Configures date-grouping on pivot field `fieldIdx`. Pass `-1` for
1988
- * `startYear` / `endYear` to leave the bound unset. */
2025
+ * `startYear` / `endYear` to leave the Year-truncation bound unset
2026
+ * (meaningful only for `PivotDateGrouping.Year`). `intervalDays` is
2027
+ * the `PivotDateGrouping.Days`-only bucket width in whole days; pass
2028
+ * `1` for every other granularity. `startSerial` / `endSerial` are
2029
+ * the `Days`-only Start/End window as Excel date serials -- pass
2030
+ * `-1` for either to leave it auto (Start = the field's data
2031
+ * minimum, End = the data maximum plus one day); ignored otherwise.
2032
+ * With `Days`, a zero `intervalDays` or a start after the end is
2033
+ * rejected with `kInvalidArgument`. */
1989
2034
  pivotFieldSetDateGroup(
1990
2035
  sheet: number,
1991
2036
  pivotIdx: number,
@@ -1994,11 +2039,15 @@ export interface Workbook {
1994
2039
  calendar: PivotCalendar,
1995
2040
  startYear: number,
1996
2041
  endYear: number,
2042
+ intervalDays: number,
2043
+ startSerial: number,
2044
+ endSerial: number,
1997
2045
  ): Status;
1998
2046
  /** Removes the date-grouping config from pivot field `fieldIdx`. */
1999
2047
  pivotFieldClearDateGroup(sheet: number, pivotIdx: number, fieldIdx: number): Status;
2000
- /** Sets the OOXML number-format string on pivot field `fieldIdx`.
2001
- * Pass an empty string to clear. */
2048
+ /** Sets the `numFmtId` of pivot field `fieldIdx`, as a decimal string
2049
+ * naming a built-in id or one returned by `addNumFmt`. Pass an empty
2050
+ * string to clear; any other unknown id is rejected. */
2002
2051
  pivotFieldSetNumberFormat(sheet: number, pivotIdx: number, fieldIdx: number, utf8: string): Status;
2003
2052
 
2004
2053
  /** Replaces the row-axis field order with `indices`. Each entry must
@@ -2008,7 +2057,7 @@ export interface Workbook {
2008
2057
  pivotSetColFieldOrder(sheet: number, pivotIdx: number, indices: ReadonlyArray<number>): Status;
2009
2058
 
2010
2059
  /** Number of `<dataField>` entries on the pivot. */
2011
- pivotDataFieldCount(sheet: number, pivotIdx: number): number;
2060
+ pivotDataFieldCount(sheet: number, pivotIdx: number): NumberResult;
2012
2061
  /** Appends a new data-field entry. */
2013
2062
  pivotDataFieldAdd(sheet: number, pivotIdx: number, spec: PivotDataFieldSpec): AddStyleResult;
2014
2063
  /** Drops every data-field entry from the pivot. */
@@ -2018,7 +2067,7 @@ export interface Workbook {
2018
2067
 
2019
2068
  /** Number of active (slicer-applied) filters on the pivot. Counts only
2020
2069
  * the entries this session added -- see {@link PivotFilterResult}. */
2021
- pivotFilterCount(sheet: number, pivotIdx: number): number;
2070
+ pivotFilterCount(sheet: number, pivotIdx: number): NumberResult;
2022
2071
  /** Appends an active filter. The entry is session state and is not
2023
2072
  * written by `save`; see {@link PivotFilterResult}. */
2024
2073
  pivotFilterAdd(sheet: number, pivotIdx: number, spec: PivotFilterSpec): Status;
@@ -2239,24 +2288,24 @@ export interface Workbook {
2239
2288
  addDxf(record: DxfRecord): AddStyleResult;
2240
2289
 
2241
2290
  /** Returns the number of font records currently registered. */
2242
- fontCount(): number;
2291
+ fontCount(): NumberResult;
2243
2292
  /** Returns the number of fill records currently registered. */
2244
- fillCount(): number;
2293
+ fillCount(): NumberResult;
2245
2294
  /** Returns the number of border records currently registered. */
2246
- borderCount(): number;
2295
+ borderCount(): NumberResult;
2247
2296
  /** Returns the number of `<xf>` records currently registered. */
2248
- xfCount(): number;
2297
+ xfCount(): NumberResult;
2249
2298
  /** Returns the number of `<dxf>` records available for CF `dxfId`. */
2250
- dxfCount(): number;
2299
+ dxfCount(): NumberResult;
2251
2300
 
2252
2301
  /** Returns the number of named cell styles (`<cellStyle>` entries)
2253
2302
  * registered. Zero for workbooks that do not declare any named
2254
2303
  * styles. */
2255
- cellStyleCount(): number;
2304
+ cellStyleCount(): NumberResult;
2256
2305
  /** Returns the number of `<cellStyleXfs>` records — the named-style
2257
2306
  * xf table referenced by `CellStyleResult.xfId`. Independent of the
2258
2307
  * per-cell `cellXfs` table. */
2259
- cellStyleXfCount(): number;
2308
+ cellStyleXfCount(): NumberResult;
2260
2309
  /** Returns the named cell style at `index`. Out-of-range indices
2261
2310
  * surface `kInvalidArgument` via `status`. */
2262
2311
  getCellStyle(index: number): CellStyleResult;
@@ -2365,11 +2414,12 @@ export interface Workbook {
2365
2414
  /** Returns the cells that `(sheet, row, col)` directly reads
2366
2415
  * (1-step precedents) when `depth <= 1`, or every cell reached
2367
2416
  * within `depth` BFS steps otherwise. `depth` is capped at 32 to
2368
- * avoid runaway expansion in cyclic graphs. */
2369
- precedents(sheet: number, row: number, col: number, depth: number): ReadonlyArray<CellNode>;
2417
+ * avoid runaway expansion in cyclic graphs. An invalid sheet, row or
2418
+ * column yields an empty list with `status.ok === false`. */
2419
+ precedents(sheet: number, row: number, col: number, depth: number): ListResult<CellNode>;
2370
2420
  /** Returns the cells that read `(sheet, row, col)` directly
2371
2421
  * (1-step dependents). Same depth semantics as `precedents`. */
2372
- dependents(sheet: number, row: number, col: number, depth: number): ReadonlyArray<CellNode>;
2422
+ dependents(sheet: number, row: number, col: number, depth: number): ListResult<CellNode>;
2373
2423
 
2374
2424
  /** Returns metadata for the function `name` (case-insensitive). When
2375
2425
  * the function is unknown, returns `{ok: false}`. `locale` selects
@@ -2379,20 +2429,21 @@ export interface Workbook {
2379
2429
  functionMetadata(name: string, locale: number): FunctionMetadataResult;
2380
2430
  /** Returns every registered function's canonical name in ascending
2381
2431
  * sort order. */
2382
- functionNames(): ReadonlyArray<string>;
2432
+ functionNames(): ListResult<string>;
2383
2433
 
2384
2434
  /** Returns the localized display name for the canonical function
2385
2435
  * `canonicalName` in `locale`. No alias table exists in any locale,
2386
2436
  * so this always returns the canonical name unchanged; localized
2387
- * display names belong to the host's provider document. Returns the
2388
- * empty string when the canonical name does not match a registered
2389
- * function. */
2390
- localizeFunctionName(canonicalName: string, locale: number): string;
2437
+ * display names belong to the host's provider document. `value` is
2438
+ * the empty string, with `status.ok === false`, when the canonical
2439
+ * name does not match a registered function. */
2440
+ localizeFunctionName(canonicalName: string, locale: number): StringResult;
2391
2441
  /** Inverse of `localizeFunctionName`: returns the canonical English
2392
2442
  * name for the localized function `localizedName`. With no alias
2393
2443
  * table this is a case-insensitive canonical-name match, in every
2394
- * locale. Returns the empty string when no function matches. */
2395
- canonicalizeFunctionName(localizedName: string, locale: number): string;
2444
+ * locale. `value` is the empty string, with `status.ok === false`,
2445
+ * when no function matches. */
2446
+ canonicalizeFunctionName(localizedName: string, locale: number): StringResult;
2396
2447
 
2397
2448
  /** Returns dynamic-array spill info for `(sheet, row, col)`.
2398
2449
  * When the cell is part of a spill region (anchor or phantom),
@@ -2409,9 +2460,10 @@ export interface WorkbookCtor {
2409
2460
  createDefault(): Workbook;
2410
2461
  /** Workbook with no sheets. */
2411
2462
  createEmpty(): Workbook;
2412
- /** Loads from an in-memory `.xlsx` byte buffer. The returned wrapper
2413
- * may be invalid (`!isValid()`) on failure; consult
2414
- * `lastErrorMessage()` for diagnostics. */
2463
+ /** Loads from an in-memory workbook byte buffer, auto-detecting
2464
+ * `.xlsx` vs `.xlsb` from the package contents (there is no filename
2465
+ * to route on). The returned wrapper may be invalid (`!isValid()`) on
2466
+ * failure; consult `lastErrorMessage()` for diagnostics. */
2415
2467
  loadBytes(bytes: Uint8Array): Workbook;
2416
2468
  }
2417
2469
 
package/dist/formulon.js CHANGED
@@ -1,144 +1,9 @@
1
- // Public ESM surface for @libraz/formulon. The generated Emscripten module
1
+ // Public ESM surface for @libraz/formulon: the single-threaded build, which
2
+ // loads without cross-origin isolation. The generated Emscripten module
2
3
  // remains an implementation detail so this shim can expose the value
3
4
  // constants declared in formulon.d.ts alongside its default factory.
4
5
 
5
6
  import createFormulon from './formulon_core.js';
6
7
 
7
8
  export default createFormulon;
8
-
9
- export const ValueKind = Object.freeze({
10
- Blank: 0,
11
- Number: 1,
12
- Bool: 2,
13
- Text: 3,
14
- Error: 4,
15
- Array: 5,
16
- Ref: 6,
17
- Lambda: 7,
18
- });
19
- export const WorkbookFormat = Object.freeze({ Unknown: 0, Xlsx: 1, Xlsb: 2 });
20
- export const PivotCellKind = Object.freeze({
21
- Header: 0,
22
- RowLabel: 1,
23
- ColLabel: 2,
24
- Data: 3,
25
- RowSubtotal: 4,
26
- ColSubtotal: 5,
27
- GrandTotal: 6,
28
- Blank: 7,
29
- });
30
- export const PivotAxis = Object.freeze({ Row: 0, Col: 1, Value: 2, Page: 3 });
31
- export const PivotAggregation = Object.freeze({
32
- Sum: 0,
33
- Count: 1,
34
- Average: 2,
35
- Max: 3,
36
- Min: 4,
37
- Product: 5,
38
- CountNumbers: 6,
39
- StdDev: 7,
40
- StdDevP: 8,
41
- Var: 9,
42
- VarP: 10,
43
- });
44
- export const PivotShowValuesAs = Object.freeze({
45
- Normal: 0,
46
- PercentOfRow: 1,
47
- PercentOfCol: 2,
48
- PercentOfTotal: 3,
49
- RunningTotalInRow: 4,
50
- RunningTotalInCol: 5,
51
- Index: 6,
52
- DifferenceFrom: 7,
53
- PercentDifferenceFrom: 8,
54
- PercentOfParentRow: 9,
55
- PercentOfParentCol: 10,
56
- PercentOfParent: 11,
57
- });
58
- export const PIVOT_SHOW_AS_BASE_PREVIOUS = 1048828;
59
- export const PIVOT_SHOW_AS_BASE_NEXT = 1048829;
60
- export const PivotFilterType = Object.freeze({
61
- ValueTop10: 0,
62
- ValueGreaterThan: 1,
63
- ValueBetween: 2,
64
- LabelContains: 3,
65
- LabelBeginsWith: 4,
66
- LabelDate: 5,
67
- });
68
- export const PivotDateGrouping = Object.freeze({
69
- Day: 0,
70
- Month: 1,
71
- Quarter: 2,
72
- Year: 3,
73
- Week: 4,
74
- Hour: 5,
75
- Minute: 6,
76
- Second: 7,
77
- });
78
- export const PivotCalendar = Object.freeze({ Gregorian: 0, Japanese: 1 });
79
- export const PivotReportLayout = Object.freeze({ Compact: 0, Tabular: 1, Outline: 2 });
80
- export const PivotFilterValueKind = Object.freeze({ None: -1, Int: 0, Double: 1, Text: 2 });
81
- export const CfMatchKind = Object.freeze({ DifferentialFormat: 0, ColorScale: 1, DataBar: 2, IconSet: 3 });
82
- export const ErrorCode = Object.freeze({
83
- Null: 0,
84
- Div0: 1,
85
- Value: 2,
86
- Ref: 3,
87
- Name: 4,
88
- Num: 5,
89
- NA: 6,
90
- GettingData: 7,
91
- Spill: 8,
92
- Calc: 9,
93
- Field: 10,
94
- Blocked: 11,
95
- Connect: 12,
96
- External: 13,
97
- Busy: 14,
98
- Python: 15,
99
- Unknown: 16,
100
- });
101
- export const CalcMode = Object.freeze({ Auto: 0, Manual: 1, AutoNoTable: 2 });
102
- export const SheetVisibility = Object.freeze({ Visible: 0, Hidden: 1, VeryHidden: 2 });
103
- export const ExternalLinkKind = Object.freeze({ Unknown: 0, ExternalBook: 1, Ole: 2, Dde: 3 });
104
- export const LogLevel = Object.freeze({ Debug: 0, Info: 1, Warn: 2, Error: 3, Off: 4 });
105
-
106
- /**
107
- * Merge a host-supplied metadata entry over the engine's structural
108
- * `functionMetadata()` result.
109
- *
110
- * This is a pure, side-effect-free helper: it does not touch the engine.
111
- * The engine returns `signatureTemplate` / `description` as
112
- * `undefined`; a host injects display metadata (see
113
- * `docs/function-metadata-schema.md`) and merges it here at display time.
114
- * The metadata is display-only and never affects formula parsing or
115
- * evaluation.
116
- *
117
- * Field precedence (first non-nullish wins):
118
- * - signatureTemplate: `entry.localized[locale].signature` ->
119
- * `entry.signature` -> `base.signatureTemplate`
120
- * - description: `entry.localized[locale].description` ->
121
- * `entry.description` -> `base.description`
122
- * - localizedName: `entry.aliases[locale]` -> `base.name`
123
- *
124
- * @param {object} base A `FunctionMetadataResult` from `functionMetadata()`.
125
- * @param {object|undefined} entry The provider's `functions[NAME]` entry, or
126
- * `undefined`/`null` to leave `base` unchanged (signature/description
127
- * stay `undefined`).
128
- * @param {string} locale A BCP-47 display locale tag (e.g. `"fr-FR"`),
129
- * matching the keys in `aliases` / `localized`. Independent of the numeric
130
- * locale code passed to `functionMetadata()`.
131
- * @returns {object} The merged metadata (a new object), or `base` verbatim
132
- * when `entry` is absent.
133
- */
134
- export function mergeFunctionMetadata(base, entry, locale) {
135
- if (entry === undefined || entry === null) {
136
- return base;
137
- }
138
- const localized = (entry.localized && entry.localized[locale]) || {};
139
- const signatureTemplate = localized.signature ?? entry.signature ?? base.signatureTemplate;
140
- const description = localized.description ?? entry.description ?? base.description;
141
- const aliasName = entry.aliases && entry.aliases[locale];
142
- const localizedName = aliasName ?? base.name;
143
- return { ...base, signatureTemplate, description, localizedName };
144
- }
9
+ export * from './common.js';
Binary file