@sheetxl/primitives 0.8.0-beta.14 → 0.8.0-beta.16

package/LICENSE.md

@@ -1,11 +1,21 @@
-# Repository Licensing
+MIT License
 
-SheetXL contains a mix of open-source and commercially licensed packages. Each package is individually licensed and contains its own license file.
+Copyright (c) 2026-present SheetXL Inc. & Michael T. Ford
 
-For the specific terms and conditions applicable to a package, please see the `LICENSE.md` file located in that package's root directory.
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
 
-Generally, packages intended for public distribution (such as CLIs, adapters, and vanilla wrappers) are licensed under the MIT license. All other core packages are proprietary and require a commercial license for use.
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
 
-For more details on commercial licensing, please visit our website:
-
-https://www.sheetxl.com/docs/guides/licensing-pricing
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/browser/esm/index.mjs

@@ -1,8 +1,8 @@
 /**
-* @license @sheetxl/primitives - Primitives - Base types for SheetXL functions. - v0.8.0-beta.14
+* @license @sheetxl/primitives - Primitives - Base types for SheetXL functions. - v0.8.0-beta.16
 *
 * (C) 2026-present SheetXL Inc. & Michael T. Ford
-* License: The license can be found at https://www.sheetxl.com/license.
+* License: MIT
 */
 var e;
 (function(e) {
@@ -492,8 +492,11 @@ var v = class {
 	createCriteria(e, t) {
 		throw x("createCriteria");
 	}
-	createGrouping(e, t) {
-		throw x("createGrouping");
+	createPivot(e, t, n) {
+		throw x("createPivot");
+	}
+	getPivotAt(e) {
+		return null;
 	}
 	parseAsLiteral(e) {
 		let t = e.toUpperCase();
@@ -576,8 +579,11 @@ var v = class {
 	createCriteria(e, t) {
 		return this._getScope().createCriteria(e, t);
 	}
-	createGrouping(e, t) {
-		return this._getScope().createGrouping(e, t);
+	createPivot(e, t, n) {
+		return this._getScope().createPivot(e, t, n);
+	}
+	getPivotAt(e) {
+		return this._getScope().getPivotAt?.(e) ?? null;
 	}
 	parseAsLiteral(e) {
 		let t = this._getScope();

package/node/esm/index.mjs

@@ -1,8 +1,8 @@
 /**
-* @license @sheetxl/primitives - Primitives - Base types for SheetXL functions. - v0.8.0-beta.14
+* @license @sheetxl/primitives - Primitives - Base types for SheetXL functions. - v0.8.0-beta.16
 *
 * (C) 2026-present SheetXL Inc. & Michael T. Ford
-* License: The license can be found at https://www.sheetxl.com/license.
+* License: MIT
 */
 var e;
 (function(e) {
@@ -314,7 +314,7 @@ var t, r, o, n, s = {
 		}
 	}
 	e.Field = f;
-	class b extends o {
+	class A extends o {
 		constructor(e, o) {
 			super(t.Calc, r.Calc, e, o);
 		}
@@ -322,8 +322,8 @@ var t, r, o, n, s = {
 			this.code = n.Code.Calc;
 		}
 	}
-	e.Calc = b;
-	class A extends o {
+	e.Calc = A;
+	class b extends o {
 		constructor(e, o) {
 			super(t.Busy, r.Busy, e, o);
 		}
@@ -331,7 +331,7 @@ var t, r, o, n, s = {
 			this.code = n.Code.Busy;
 		}
 	}
-	e.Busy = A;
+	e.Busy = b;
 	class N extends o {
 		constructor(e, o) {
 			super(t.Python, r.Python, e, o);
@@ -406,7 +406,7 @@ var f = class {
 			"function" == typeof n && n();
 		}, o;
 	}
-}, b = class {
+}, A = class {
 	createRange(e, t, r) {
 		throw N("createRange");
 	}
@@ -497,8 +497,11 @@ var f = class {
 	createCriteria(e, t) {
 		throw N("createCriteria");
 	}
-	createGrouping(e, t) {
-		throw N("createGrouping");
+	createPivot(e, t, r) {
+		throw N("createPivot");
+	}
+	getPivotAt(e) {
+		return null;
 	}
 	parseAsLiteral(e) {
 		const t = e.toUpperCase();
@@ -509,7 +512,7 @@ var f = class {
 	}
 	compare(e, t, r) {
 		if (e === t) return 0;
-		const o = A(e), n = A(t);
+		const o = b(e), n = b(t);
 		return o !== n ? o < n ? -1 : 1 : e < t ? -1 : e > t ? 1 : 0;
 	}
 	getRuntime() {
@@ -521,7 +524,7 @@ var f = class {
 	createRichData(e, t) {
 		throw new w(y);
 	}
-}, A = (e) => {
+}, b = (e) => {
 	if (null == e) return 0;
 	switch (typeof e) {
 		case "number": return 1;
@@ -540,8 +543,8 @@ var f = class {
 	rowEnd: Math.pow(2, 20) - 1
 }), R = {
 	isDate1904: () => !1,
-	getLocale: () => k.tag,
-	getLocaleProfile: () => k,
+	getLocale: () => T.tag,
+	getLocaleProfile: () => T,
 	isR1C1: () => !1,
 	getNow: () => 0,
 	getRandom: () => Math.random(),
@@ -550,7 +553,7 @@ var f = class {
 	getOS: () => "unknown",
 	getUser: () => "unidentified",
 	getDescription: () => "Stubbed Formula Context"
-}, x = 2958465, F = new b(), T = class {
+}, x = 2958465, F = new A(), P = class {
 	constructor() {
 		this._scope = F, this._argsFn = null;
 	}
@@ -581,8 +584,11 @@ var f = class {
 	createCriteria(e, t) {
 		return this._getScope().createCriteria(e, t);
 	}
-	createGrouping(e, t) {
-		return this._getScope().createGrouping(e, t);
+	createPivot(e, t, r) {
+		return this._getScope().createPivot(e, t, r);
+	}
+	getPivotAt(e) {
+		return this._getScope().getPivotAt?.(e) ?? null;
 	}
 	parseAsLiteral(e) {
 		const t = this._getScope();
@@ -696,7 +702,7 @@ var f = class {
 	toString() {
 		return this._getScope()?.toString?.() ?? "{STUB SCOPE}";
 	}
-}, k = Object.freeze({
+}, T = Object.freeze({
 	tag: "en-US",
 	numberingSystem: "latn",
 	decimal: ".",
@@ -776,5 +782,5 @@ var f = class {
 		sensitivity: "base",
 		numeric: !0
 	})
-}), P = new T();
-export { k as DEFAULT_LOCALE_PROFILE, P as FormulaContext, n as FormulaError, t as IRange, o as IRangeStats, a as InteropScalarType, f as Observable, e as Scalar, s as ScalarType, T as ScopedFormulaContext, b as StubbedFormulaContext, i as ValueKind, l as WildCard, d as isLazyValue };
+}), k = new P();
+export { T as DEFAULT_LOCALE_PROFILE, k as FormulaContext, n as FormulaError, t as IRange, o as IRangeStats, a as InteropScalarType, f as Observable, e as Scalar, s as ScalarType, P as ScopedFormulaContext, A as StubbedFormulaContext, i as ValueKind, l as WildCard, d as isLazyValue };

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@sheetxl/primitives",
   "description": "Primitives - Base types for SheetXL functions.",
-  "version": "0.8.0-beta.14",
-  "license": "SEE LICENSE IN <LICENSE>",
+  "version": "0.8.0-beta.16",
+  "license": "MIT",
   "type": "module",
   "exports": {
     ".": {

package/types/src/FormulaContext.d.ts

@@ -94,12 +94,16 @@ export declare class StubbedFormulaContext implements IFormulaContext {
      */
     createCriteria(criteria: Scalar, options?: IFormulaContext.CriteriaOptions): IFormulaContext.CriteriaEvaluator;
     /**
-     * Unimplemented. See {@link IFormulaContext.createGrouping}.
+     * Unimplemented. See {@link IFormulaContext.createPivot}.
      *
      * @remarks
-     * Grouping needs the engine's key equality, which this stub does not have.
+     * A pivot needs the engine's key equality, which this stub does not have.
      */
-    createGrouping(keys: IRange, options?: IFormulaContext.GroupingOptions): IFormulaContext.Grouping;
+    createPivot(rows: IRange | null, columns: IRange | null, options?: IFormulaContext.PivotOptions): IFormulaContext.Pivot;
+    /**
+     * No pivot tables. See {@link IFormulaContext.getPivotAt}.
+     */
+    getPivotAt(_reference: IReferenceRange): IFormulaContext.PivotView | null;
     /**
      * Parses the canonical English boolean and error literals.
      * See {@link IFormulaContext.parseAsLiteral}.
@@ -190,8 +194,10 @@ export declare class ScopedFormulaContext implements IFormulaContext {
     parseAsNumber(textOrNumber: Scalar | undefined, options?: IFormulaContext.ParseNumberOptions): number | undefined;
     /** @inheritdoc IFormulaContext.createCriteria */
     createCriteria(criteria: Scalar, options?: IFormulaContext.CriteriaOptions): IFormulaContext.CriteriaEvaluator;
-    /** @inheritdoc IFormulaContext.createGrouping */
-    createGrouping(keys: IRange, options?: IFormulaContext.GroupingOptions): IFormulaContext.Grouping;
+    /** @inheritdoc IFormulaContext.createPivot */
+    createPivot(rows: IRange | null, columns: IRange | null, options?: IFormulaContext.PivotOptions): IFormulaContext.Pivot;
+    /** @inheritdoc IFormulaContext.getPivotAt */
+    getPivotAt(reference: IReferenceRange): IFormulaContext.PivotView | null;
     /** @inheritdoc IFormulaContext.parseAsLiteral */
     parseAsLiteral(text: string): boolean | FormulaError.Known | undefined;
     /** @inheritdoc IFormulaContext.toText */

package/types/src/IFormulaContext.d.ts

@@ -39,7 +39,7 @@ import { IRichData } from './IRichData';
  * | Dates | `getNow`, `toSerialDate`, `fromSerialDate`, `getDateParts`, `getSerialDate`, `parseAsDate`, `parseAsSerialDate`, `isValidDate` |
  * | Coercion | `parseAsNumber`, `parseAsLiteral`, `toText`, `compare` |
  * | Criteria | `createCriteria` |
- * | Grouping | `createGrouping` |
+ * | Grouping | `createPivot`, `getPivotAt` |
  * | Sheet introspection | `getSheetCount`, `getSheetIndex`, `getAddress`, `getNumberFormat` |
  *
  * ### Implementors
@@ -351,32 +351,50 @@ export interface IFormulaContext {
      */
     createCriteria(criteria: Scalar, options?: IFormulaContext.CriteriaOptions): IFormulaContext.CriteriaEvaluator;
     /**
-     * Groups the records of a range — its rows — by their values.
+     * Groups the records of a range two ways at once — by row keys and by column keys — at every
+     * key level of each, and crosses every row group with every column group.
      *
-     * @param keys The key columns. Each row is one record, and records with equal values in every
-     * column form one group.
-     * @param options Which records take part. See {@link IFormulaContext.GroupingOptions}.
-     * @returns The groups, numbered in the order they first appear.
+     * @param rows The row key columns, or `null` for none: every record is then in the one row group.
+     * @param columns The column key columns, or `null` for none.
+     * @param options Which records take part. See {@link IFormulaContext.PivotOptions}.
+     * @returns The two axes of groups and what their crossings hold.
+     * @throws `#VALUE!` for more than 32 key columns on one axis, or more groups and crossings than
+     * the pivot can number.
      *
      * @remarks
-     * Two keys are equal by the rule `UNIQUE` uses: text ignores case, and types never mix, so `1`,
-     * `"1"` and `TRUE` are three groups. A blank key is a key of its own, distinct from `""`, and an
-     * error is a key like any other value. Every row is a record, blank rows included.
+     * Every row is a record, blank rows included. Two keys are equal by the rule `UNIQUE` uses: text
+     * ignores case, and types never mix, so `1`, `"1"` and `TRUE` are three groups. A blank key is a
+     * key of its own, distinct from `""`, and an error is a key like any other value.
      *
-     * Group ONCE and ask the grouping for each group's members. The grouping does the work a
-     * per-group scan would repeat, so it stays proportional to the data rather than to the data
-     * times the number of groups.
+     * Each axis is a tree: its root is every kept record, the root's children are the groups of the
+     * first key column, theirs add the second, and so on, each in the order its first record appears.
+     * A subtotal is then one group, never a union of its children.
+     *
+     * One pivot answers what a grouping per key level, and another per pair of levels, would — in
+     * one pass, which is what `PIVOTBY` and a pivot table need.
      *
      * @example
      * ```typescript
-     * const grouping = FormulaContext.createGrouping(regions);
-     * for (let g = 0; g < grouping.getGroupCount(); g++) {
-     *   const [region] = grouping.getKeys(g);
-     *   const sales = grouping.getMembers(amounts, [g]);
+     * const pivot = FormulaContext.createPivot(regions, years);
+     * for (const region of pivot.getRows().getRoot().getChildren()) {
+     *   const total = pivot.getMembers(sales, region); // every year
+     *   const [name] = region.getKeys();
      * }
      * ```
      */
-    createGrouping(keys: IRange, options?: IFormulaContext.GroupingOptions): IFormulaContext.Grouping;
+    createPivot(rows: IRange | null, columns: IRange | null, options?: IFormulaContext.PivotOptions): IFormulaContext.Pivot;
+    /**
+     * The pivot table a reference touches, as the values it shows.
+     *
+     * @param reference Any cell or range of the table, its page fields included.
+     * @returns The view, or `null` when the reference touches no pivot table, or the table's values
+     * are not computed (it is not modeled, or its view has not loaded yet).
+     *
+     * @remarks
+     * What `GETPIVOTDATA` reads. The view answers for the values the table shows; matching a request
+     * to its fields and items by name is the caller's.
+     */
+    getPivotAt(reference: IReferenceRange): IFormulaContext.PivotView | null;
     /**
      * Reads a typed literal in the workbook's language — the parse side of {@link toText}.
      *
@@ -724,9 +742,9 @@ export declare namespace IFormulaContext {
         anchor?: 'whole' | 'start';
     }
     /**
-     * Options for {@link IFormulaContext.createGrouping}.
+     * Options for {@link IFormulaContext.createPivot}.
      */
-    interface GroupingOptions {
+    interface PivotOptions {
         /**
          * One column, as tall as the keys, selecting the records that take part. A record is kept
          * when its member is `TRUE` or a nonzero number, and left out otherwise.
@@ -734,48 +752,148 @@ export declare namespace IFormulaContext {
         filter?: IRange;
     }
     /**
-     * The records of a range divided into groups — see {@link IFormulaContext.createGrouping}.
+     * The records of a range grouped by rows and by columns — see {@link IFormulaContext.createPivot}.
      */
-    interface Grouping {
+    interface Pivot {
         /**
          * The number of records kept by the filter.
          */
         getRecordCount(): number;
         /**
-         * The number of groups.
+         * The row groups.
          */
-        getGroupCount(): number;
+        getRows(): PivotAxis;
         /**
-         * The number of records in a group.
+         * The column groups.
          */
-        getSize(group: number): number;
+        getColumns(): PivotAxis;
         /**
-         * A group's key, one value per key column, as spelled by the group's first record. A blank
-         * key is `null`.
+         * The members of `values` in both a row group and a column group, as one column in record order.
+         *
+         * @param values One column, as tall as the keys.
+         * @param row A group of this pivot's rows; omit it, or pass the root, for every row.
+         * @param column A group of this pivot's columns; omit it, or pass the root, for every column.
+         * @returns An array, never a reference, or `null` when no kept record is in both groups.
          */
-        getKeys(group: number): readonly Scalar[];
+        getMembers(values: IRange, row?: PivotGroup, column?: PivotGroup): IRange | null;
         /**
-         * The group a record belongs to, or `-1` when the filter left it out.
+         * What `fn` returns over the members {@link getMembers} would give, computed without them.
+         *
+         * @returns `null` when no kept record is in both groups, `undefined` when the pivot does not
+         * compute `fn` this way: call `fn` over {@link getMembers} instead.
          *
-         * @param record The record's row within the keys.
+         * @remarks
+         * Optional. Where it is present it answers for the built-in aggregates it knows (`SUM`,
+         * `COUNT`, `AVERAGE`, ...) with exactly the value the call would return, the first error
+         * member included.
+         */
+        getAggregate?(values: IRange, fn: IFunction, row?: PivotGroup, column?: PivotGroup): Scalar | null | undefined;
+    }
+    /**
+     * A pivot table as the values it shows — see {@link IFormulaContext.getPivotAt}.
+     */
+    interface PivotView {
+        /**
+         * The table's values, in its order.
          */
-        getGroup(record: number): number;
+        getDataFields(): readonly PivotViewDataField[];
         /**
-         * The row of a group's first record within the keys.
+         * The fields on the table's rows, columns and pages, in that order.
+         */
+        getFields(): readonly PivotViewField[];
+        /**
+         * A value the table shows.
          *
-         * @remarks
-         * With {@link getGroup} on another grouping of the same records, this maps a group of one
-         * grouping onto the group of another — a finer grouping's group onto its parent's.
+         * @param dataField The value, by index into {@link getDataFields}.
+         * @param items Per field, by index into {@link getFields}, the item by index into its
+         * {@link PivotViewField.items}. A field left out is totaled over.
+         * @returns The value, or `undefined` when the table does not show it: a line it does not show
+         * (a hidden or collapsed item, a subtotal or grand total turned off), an item not on its page,
+         * or a crossing with no records.
          */
-        getFirstRecord(group: number): number;
+        getValue(dataField: number, items: ReadonlyMap<number, number>): Scalar | undefined;
         /**
-         * The members of `values` that belong to some groups, as one column in record order.
+         * Whether the table's values are known here.
          *
-         * @param values One column, as tall as the keys.
-         * @param groups The groups to take members from. Omit it for every kept record.
-         * @returns An array, never a reference. A blank member stays blank.
+         * @returns `false` for a table that is there but whose values the host does not compute: its
+         * fields and values are empty, and a caller that answered from it before keeps that answer, as
+         * the table only changes on a refresh. Absent means `true`.
+         */
+        isComputed?(): boolean;
+    }
+    /**
+     * A value of a {@link PivotView}.
+     */
+    interface PivotViewDataField {
+        /** As the table shows it (`Sum of Sales`). */
+        readonly name: string;
+        /** The name of the source field it summarizes (`Sales`). */
+        readonly sourceName: string;
+    }
+    /**
+     * A field of a {@link PivotView}.
+     */
+    interface PivotViewField {
+        /** As the table shows it: its caption, or the source field's name. */
+        readonly name: string;
+        readonly items: readonly PivotViewItem[];
+    }
+    /**
+     * An item of a {@link PivotViewField}.
+     */
+    interface PivotViewItem {
+        /** The item's value; `null` for the blank item. */
+        readonly value: Scalar;
+        /** The value as the table shows it, in the field's number format; `(blank)` for the blank item. */
+        readonly text: string;
+        /** The caption the item was renamed to, if it was. */
+        readonly name?: string;
+    }
+    /**
+     * One axis of a {@link Pivot}: its groups at every key level, as a tree under one root.
+     */
+    interface PivotAxis {
+        /**
+         * The group of every kept record, at level `0`.
+         */
+        getRoot(): PivotGroup;
+        /**
+         * The number of groups, the root included.
+         */
+        getGroupCount(): number;
+    }
+    /**
+     * One group of a {@link PivotAxis}. The axis answers the same object for a group every time, so a
+     * group can key a map.
+     */
+    interface PivotGroup {
+        /**
+         * The number of key columns the group is keyed by: `0` for the root, `1` for the groups of the
+         * first key column, and so on.
+         */
+        getLevel(): number;
+        /**
+         * The group one level up, or `null` for the root.
+         */
+        getParent(): PivotGroup | null;
+        /**
+         * The groups one level down, in the order their first records appear.
+         */
+        getChildren(): readonly PivotGroup[];
+        /**
+         * The keys, one per level down to this group's own. Each level's key is spelled by the first
+         * record of the group at that level, so a group's keys begin with its parent's. A blank key is
+         * `null`.
+         */
+        getKeys(): readonly Scalar[];
+        /**
+         * The number of kept records in the group.
+         */
+        getSize(): number;
+        /**
+         * The row of the group's first record within the keys.
          */
-        getMembers(values: IRange, groups?: readonly number[]): IRange;
+        getFirstRecord(): number;
     }
     /**
      * A serial date split into fields — see {@link IFormulaContext.getDateParts}.