@sheetxl/primitives 0.8.0-beta.1 → 0.8.0-beta.11

package/types/src/FormulaContext.d.ts

@@ -21,6 +21,8 @@ import { LocaleProfile } from './LocaleProfile';
 export declare class StubbedFormulaContext implements IFormulaContext {
     /** @inheritdoc IFormulaContext.createRange */
     createRange<TS extends Scalar = Scalar>(rows?: number, columns?: number, values?: Scalar | Scalar[][] | ((value: TS, coords: IRange.CellCoords, range: IRange<TS>) => TS)): IRange;
+    /** @inheritdoc IFormulaContext.flattenAreas */
+    flattenAreas(value: IRange | IRange[]): IRange;
     /** @inheritdoc IFormulaContext.getReference */
     getReference(coords?: Readonly<IRange.Coords>, r1c1?: boolean): IReferenceRange;
     /** @inheritdoc IFormulaContext.getResizedReference */
@@ -37,6 +39,8 @@ export declare class StubbedFormulaContext implements IFormulaContext {
     getSerialDate(year: number, month: number, day: number, hour?: number, minute?: number, second?: number, millis?: number): number;
     /** @inheritdoc IFormulaContext.getNow */
     getNow(): number;
+    /** @inheritdoc IFormulaContext.getRandom */
+    getRandom(): number;
     /** @inheritdoc IFormulaContext.getValueAt */
     getValueAt(row: number, column: number, sheetName?: string, options?: IRange.ValueOptions): Scalar | null;
     /** @inheritdoc IFormulaContext.getEntireCoords */
@@ -47,6 +51,8 @@ export declare class StubbedFormulaContext implements IFormulaContext {
     getRow(): number;
     /** @inheritdoc IFormulaContext.getColumn */
     getColumn(): number;
+    /** @inheritdoc IFormulaContext.isImplicitIntersect */
+    isImplicitIntersect(): boolean;
     /** @inheritdoc IFormulaContext.getFormulaAt */
     getFormulaAt(row: number, column: number, sheetName?: string): string | null;
     /** @inheritdoc IFormulaContext.getSpillAt */
@@ -60,7 +66,7 @@ export declare class StubbedFormulaContext implements IFormulaContext {
     /** @inheritdoc IFormulaContext.formatResults */
     formatResults(numFmt: string): void;
     /** @inheritdoc IFormulaContext.filterHidden */
-    filterHidden(range: IRange, axes?: IRange.AxisSelection): IRange;
+    filterHidden(range: IRange, options?: IFormulaContext.FilterHiddenOptions): IRange;
     /** @inheritdoc IFormulaContext.filterTotals */
     filterTotals(range: IRange): IRange;
     /** @inheritdoc IFormulaContext.getFunction */
@@ -83,7 +89,14 @@ export declare class StubbedFormulaContext implements IFormulaContext {
      * plausibly and wrongly, where throwing names the actual mistake (evaluating criteria outside an
      * installed scope).
      */
-    createCriteria(criteria: Scalar): IFormulaContext.CriteriaEvaluator;
+    createCriteria(criteria: Scalar, options?: IFormulaContext.CriteriaOptions): IFormulaContext.CriteriaEvaluator;
+    /**
+     * Unimplemented. See {@link IFormulaContext.createGrouping}.
+     *
+     * @remarks
+     * Grouping needs Excel's key equality, which this stub does not have.
+     */
+    createGrouping(keys: IRange, options?: IFormulaContext.GroupingOptions): IFormulaContext.Grouping;
     /**
      * Parses the canonical English boolean and error literals.
      * See {@link IFormulaContext.parseAsLiteral}.
@@ -171,7 +184,9 @@ export declare class ScopedFormulaContext implements IFormulaContext {
     parseAsNumber(textOrNumber: Scalar, options?: IFormulaContext.ParseNumberOptions): number;
     parseAsNumber(textOrNumber: Scalar | undefined, options?: IFormulaContext.ParseNumberOptions): number | undefined;
     /** @inheritdoc IFormulaContext.createCriteria */
-    createCriteria(criteria: Scalar): IFormulaContext.CriteriaEvaluator;
+    createCriteria(criteria: Scalar, options?: IFormulaContext.CriteriaOptions): IFormulaContext.CriteriaEvaluator;
+    /** @inheritdoc IFormulaContext.createGrouping */
+    createGrouping(keys: IRange, options?: IFormulaContext.GroupingOptions): IFormulaContext.Grouping;
     /** @inheritdoc IFormulaContext.parseAsLiteral */
     parseAsLiteral(text: string): boolean | FormulaError.Known | undefined;
     /** @inheritdoc IFormulaContext.toText */
@@ -188,12 +203,18 @@ export declare class ScopedFormulaContext implements IFormulaContext {
     getSerialDate(year: number, month: number, day: number, hour?: number, minute?: number, second?: number, millis?: number): number;
     /** @inheritdoc IFormulaContext.getNow */
     getNow(): number;
+    /** @inheritdoc IFormulaContext.getRandom */
+    getRandom(): number;
     /** @inheritdoc IFormulaContext.createRange */
     createRange<TS extends Scalar = Scalar>(rows?: number, columns?: number, values?: Scalar | Scalar[][] | ((value: TS, coords: IRange.CellCoords, range: IRange<TS>) => TS)): IRange;
+    /** @inheritdoc IFormulaContext.flattenAreas */
+    flattenAreas(value: IRange | IRange[]): IRange;
     /** @inheritdoc IFormulaContext.getRow */
     getRow(): number;
     /** @inheritdoc IFormulaContext.getColumn */
     getColumn(): number;
+    /** @inheritdoc IFormulaContext.isImplicitIntersect */
+    isImplicitIntersect(): boolean;
     /** @inheritdoc IFormulaContext.getReference */
     getReference(coords?: Readonly<IRange.Coords>, r1c1?: boolean): IReferenceRange;
     /** @inheritdoc IFormulaContext.getResizedReference */
@@ -213,7 +234,7 @@ export declare class ScopedFormulaContext implements IFormulaContext {
     /** @inheritdoc IFormulaContext.formatResults */
     formatResults(numFmt: string): void;
     /** @inheritdoc IFormulaContext.filterHidden */
-    filterHidden(range: IRange, axes?: IRange.AxisSelection): IRange;
+    filterHidden(range: IRange, options?: IFormulaContext.FilterHiddenOptions): IRange;
     /** @inheritdoc IFormulaContext.filterTotals */
     filterTotals(range: IRange): IRange;
     /** @inheritdoc IFormulaContext.getFunction */
@@ -232,13 +253,15 @@ export declare class ScopedFormulaContext implements IFormulaContext {
 /**
  * A plain en-US profile, for stubs and for environments without `Intl`.
  *
- * @remarks
- * Deliberately static data -- no probing. Real profiles come from
- * `makeLocaleProfile` in `@sheetxl/sdk`.
+ * @internal
+ * @hidden
  */
 export declare const DEFAULT_LOCALE_PROFILE: LocaleProfile;
 /**
  * The shared {@link IFormulaContext} for formula implementations. See {@link ScopedFormulaContext}.
+ *
+ * @internal
+ * @hidden
  */
 export declare const FormulaContext: IFormulaContext;
 //# sourceMappingURL=FormulaContext.d.ts.map

package/types/src/IFormulaContext.d.ts

@@ -28,15 +28,16 @@ import { IRuntime } from './IRuntime';
  *
  * | Category | Key methods |
  * |---|---|
- * | Evaluation lifecycle | `markVolatile`, `getRow`, `getColumn`, `getEntireCoords` |
+ * | Evaluation lifecycle | `markVolatile`, `getRow`, `getColumn`, `getEntireCoords`, `getRandom` |
  * | Argument reflection | `getArgs` |
  * | Output hints | `formatResults` |
- * | Range construction | `createRange`, `filterHidden` |
+ * | Range construction | `createRange`, `flattenAreas`, `filterHidden` |
  * | Dynamic references | `getReference`, `getValueAt`, `getFormulaAt`, `getSpillAt` |
  * | Function lookup | `getFunction` |
  * | Dates | `getNow`, `toSerialDate`, `fromSerialDate`, `getDateParts`, `getSerialDate`, `parseAsDate`, `parseAsSerialDate`, `isValidDate` |
  * | Coercion | `parseAsNumber`, `parseAsLiteral`, `toText`, `compare` |
  * | Criteria | `createCriteria` |
+ * | Grouping | `createGrouping` |
  * | Sheet introspection | `getSheetCount`, `getSheetIndex`, `getAddress`, `getNumberFormat` |
  *
  * ### Implementors
@@ -54,6 +55,25 @@ export interface IFormulaContext {
      * invoked per cell. Default is `null` (an empty range).
      */
     createRange<TS extends Scalar = Scalar>(rows?: number, columns?: number, values?: Scalar | Scalar[][] | ((value: TS, coords: IRange.CellCoords, range: IRange<TS>) => TS)): IRange;
+    /**
+     * One range over every cell of a `ReportType` slot's argument — the AREAS of a reference union
+     * folded into a single column, or the range returned unchanged.
+     *
+     * @param value The argument as it arrived: a range, or one range per area.
+     *
+     * @remarks
+     * A union `(A1:A5,B1:B2)` reaches a {@link IFunction.ParameterTypeJSON.reportType} slot as one
+     * `IRange` per area. Functions that answer over it do so because they walk MEMBERS and a union
+     * simply has more of them — `LARGE((DA1:DA5,DK1:DK2),2)` is the second largest of all seven
+     * cells. This is that walk, and it is a helper rather than a marshalling step on purpose: Excel
+     * flattens in exactly the same place, a shared reducer its bodies opt into, which is why the
+     * same union is flattened by `LARGE`, refused by `SUMPRODUCT` and answered `#REF!` by `ROWS`.
+     *
+     * The result is a single column in area order, row-major within each area. SHAPE IS NOT
+     * PRESERVED — a union has none. A body that needs an extent must ask
+     * {@link IFunctionArguments.getAreaCountAt} and answer for itself.
+     */
+    flattenAreas(value: IRange | IRange[]): IRange;
     /**
      * Returns coordinates as an address string.
      *
@@ -94,6 +114,20 @@ export interface IFormulaContext {
      * Returns the 0-based column of the cell being evaluated.
      */
     getColumn(): number;
+    /**
+     * Whether the call being evaluated is in Excel's VALUE mode, where a multi-cell reference at a
+     * slot that reads ONE value is implicitly intersected with the formula's cell (the `@` rule);
+     * `false` is ARRAY mode, where such a slot reads the reference's first cell.
+     *
+     * @remarks
+     * Only a body that accepts a whole reference at a single-value slot and reads it itself asks
+     * (`LINEST`'s `const`). The engine decides the mode from the formula around the call — a
+     * scalar-valued root, an aggregator or a lookup above it are value mode; a spilling root, an
+     * operator or lifting slot over an array-valued operand, a `LAMBDA` body and an array-entered
+     * block are array mode — and the mode is inherited through every call that does not set it.
+     * Outside a calculation this is `false`.
+     */
+    isImplicitIntersect(): boolean;
     /**
      * Resolves a range reference at runtime, returning an {@link IReferenceRange}.
      *
@@ -186,16 +220,30 @@ export interface IFormulaContext {
      */
     getSheetIndex(sheet?: string | IReferenceRange): number;
     /**
-     * Returns a copy of a range with hidden rows or columns removed.
+     * Returns a range as it reads without its hidden rows or columns.
      *
      * @param range The range to filter.
-     * @param axes Which axis to filter on. Default is `IRange.AxisSelection.Row`.
-     * @returns A new range without the hidden rows or columns.
+     * @param options See {@link IFormulaContext.FilterHiddenOptions}.
+     * @returns `range` itself when nothing in it is hidden; otherwise the same range reading with
+     * the hidden rows or columns skipped ({@link IRange.IteratorOptions.processRowSkip}).
      *
      * @remarks
      * Use this for functions that ignore hidden data, such as `SUBTOTAL`.
+     *
+     * Nothing is copied. The shape of `range` is kept, and a reference stays a reference: a hidden
+     * cell is not visited and reads as empty, so every position still means the cell it meant, and
+     * an aggregate that ignores blanks ignores it. A computed array has no rows or columns to hide
+     * and is returned as it is.
+     *
+     * A hidden row is a hidden row, whoever hid it: a filter and the user leave the same mark, and
+     * nothing here tells them apart. What a filter adds is a state of the range's SHEET, which
+     * {@link IFormulaContext.FilterHiddenOptions.onlyWhileFiltered} reads.
+     *
+     * A formula that calls `SUBTOTAL` or `AGGREGATE` is recalculated when a row or column is hidden
+     * or shown, and when a filter is set or cleared. One that reaches this only through a custom
+     * function is not: it reads the state when it is next calculated.
      */
-    filterHidden(range: IRange, axes?: IRange.AxisSelection): IRange;
+    filterHidden(range: IRange, options?: IFormulaContext.FilterHiddenOptions): IRange;
     /**
      * Returns a copy of a range with any cell whose formula is a nested total removed.
      *
@@ -277,6 +325,7 @@ export interface IFormulaContext {
      *
      * @param criteria The criteria, exactly as the user wrote it — a comparison (`">10"`, `"<>x"`),
      * a wildcard pattern (`"a*"`), or a literal of any type.
+     * @param options How the criteria is matched. See {@link IFormulaContext.CriteriaOptions}.
      * @returns A predicate to test cell values with. Call it once per cell.
      *
      * @remarks
@@ -298,7 +347,34 @@ export interface IFormulaContext {
      * const count = range.reduce((total, value) => matches(value) ? total + 1 : total, 0);
      * ```
      */
-    createCriteria(criteria: Scalar): IFormulaContext.CriteriaEvaluator;
+    createCriteria(criteria: Scalar, options?: IFormulaContext.CriteriaOptions): IFormulaContext.CriteriaEvaluator;
+    /**
+     * Groups the records of a range — its rows — by their values.
+     *
+     * @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.
+     *
+     * @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.
+     *
+     * 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.
+     *
+     * @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]);
+     * }
+     * ```
+     */
+    createGrouping(keys: IRange, options?: IFormulaContext.GroupingOptions): IFormulaContext.Grouping;
     /**
      * Reads a typed literal in the workbook's language — the parse side of {@link toText}.
      *
@@ -386,6 +462,30 @@ export interface IFormulaContext {
      * ```
      */
     getNow(): number;
+    /**
+     * Returns a random number in `[0, 1)`, like `Math.random()`.
+     *
+     * @remarks
+     * Always draw through this, never `Math.random()`. The source is the runtime's, so a test or a
+     * replay can seed it, and the engine sees the draw: a draw is a PER-CELL read — two cells calling
+     * the same function in one pass differ — where `getNow` is one value for the whole pass, and the
+     * engine only shares an evaluation across the cells of a block when nothing per-cell was read.
+     * Pair it with `Volatile<T>` so the function draws again on the next pass.
+     *
+     * Under a seeded runtime ({@link IRuntime.getRandomSeed}) each draw is keyed by the cell, the
+     * pass and which draw it is within that cell, so a function that draws more than once gets
+     * distinct values and a cell gets the same ones however the pass was ordered. Take the draws
+     * where they are used rather than hoisting them, and the values follow the cells rather than
+     * the code path.
+     *
+     * @example
+     * ```typescript
+     * export function RAND(): Volatile<number> {
+     *   return FormulaContext.getRandom();
+     * }
+     * ```
+     */
+    getRandom(): number;
     /**
      * Returns `true` if the value is a usable date — either a `Date` or a number in the
      * workbook's serial date range.
@@ -447,14 +547,12 @@ export interface IFormulaContext {
      * Fields may fall outside their normal range and carry, which is what makes `DATE` and
      * `TIME` arithmetic work: month 13 is January of the next year, hour 50 is two days plus
      * two hours, and `getSerialDate(1900, 1, 0)` is serial 0. The `day` carries in SERIAL
-     * space, so it runs through the phantom `1900-02-29` — measured 25/25 by
-     * `probe-date-1900-day-overflow.ps1`.
+     * space, so it runs through the phantom `1900-02-29`.
      *
      * **This validates nothing, and that is deliberate — a caller MUST choose its own
      * policy.** No range check, no clamping, no bounds on any field, and no `DATE`-style
      * `0..1899 -> +1900` year offset. Those belong to `DATE`'s ARGUMENTS, not to the
-     * calendar, and the three things that prove it were measured together
-     * (`probe-date-arg-layer.ps1`, 2026-08-20):
+     * calendar, and three things prove it:
      *
      * * **The day policy is the caller's.** `DATE` and `DATEDIF`'s `md`/`yd` re-anchoring
      *   want the raw carry above — `DATEDIF("2020-01-31","2020-03-01","md")` is `-1`
@@ -510,6 +608,28 @@ export interface IFormulaContext {
  * {@link IFormulaContext}
  */
 export declare namespace IFormulaContext {
+    /**
+     * Options for {@link IFormulaContext.filterHidden}.
+     */
+    interface FilterHiddenOptions {
+        /**
+         * Which axis to filter on.
+         * @defaultValue `IRange.AxisSelection.Row`
+         */
+        axes?: IRange.AxisSelection;
+        /**
+         * Skip the hidden rows or columns only while the range's sheet is filtered: while some
+         * AutoFilter or table on that sheet holds a condition, whether or not it hides a row. Until
+         * then `range` is returned as it is, hidden rows included.
+         *
+         * @remarks
+         * This is `SUBTOTAL` 1-11 (Excel: they "include manually hidden rows", which is what an
+         * unfiltered sheet reads as). `SUBTOTAL` 101-111 and `AGGREGATE` leave it off and skip
+         * always.
+         * @defaultValue false
+         */
+        onlyWhileFiltered?: boolean;
+    }
     /**
      * Options for {@link IFormulaContext.parseAsNumber}.
      */
@@ -523,6 +643,80 @@ export declare namespace IFormulaContext {
      * there.
      */
     type CriteriaEvaluator = (value: Scalar) => boolean;
+    /**
+     * How a criteria is matched — see {@link IFormulaContext.createCriteria}.
+     */
+    interface CriteriaOptions {
+        /**
+         * Where a TEXT criteria has to line up with the cell: `'whole'` (the default) for the whole
+         * cell, `'start'` for a prefix.
+         *
+         * @remarks
+         * The `D` functions' criteria table is the prefix form and the `*IF` family is not: the
+         * criterion `appl` takes the row whose value is `Apple` at `DSUM` and no row at all at
+         * `COUNTIF`, and the empty criterion — a prefix of everything — takes every TEXT cell at
+         * `DSUM` where `COUNTIF` takes only a cell that IS an empty string.
+         *
+         * It applies to a criteria that stays TEXT and to nothing else. An OPERATOR turns it off
+         * (`=appl` selects no row), and so does a criteria that reads as a number, a boolean or an
+         * error — `1` does not reach a cell holding `12`.
+         */
+        anchor?: 'whole' | 'start';
+    }
+    /**
+     * Options for {@link IFormulaContext.createGrouping}.
+     */
+    interface GroupingOptions {
+        /**
+         * 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.
+         */
+        filter?: IRange;
+    }
+    /**
+     * The records of a range divided into groups — see {@link IFormulaContext.createGrouping}.
+     */
+    interface Grouping {
+        /**
+         * The number of records kept by the filter.
+         */
+        getRecordCount(): number;
+        /**
+         * The number of groups.
+         */
+        getGroupCount(): number;
+        /**
+         * The number of records in a group.
+         */
+        getSize(group: number): number;
+        /**
+         * A group's key, one value per key column, as spelled by the group's first record. A blank
+         * key is `null`.
+         */
+        getKeys(group: number): readonly Scalar[];
+        /**
+         * The group a record belongs to, or `-1` when the filter left it out.
+         *
+         * @param record The record's row within the keys.
+         */
+        getGroup(record: number): number;
+        /**
+         * The row of a group's first record within the keys.
+         *
+         * @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.
+         */
+        getFirstRecord(group: number): number;
+        /**
+         * The members of `values` that belong to some groups, as one column in record order.
+         *
+         * @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.
+         */
+        getMembers(values: IRange, groups?: readonly number[]): IRange;
+    }
     /**
      * A serial date split into fields — see {@link IFormulaContext.getDateParts}.
      *