@sheetxl/primitives 0.7.28-beta.4 → 0.8.0-beta.2

package/types/src/FormulaContext.d.ts

@@ -3,6 +3,7 @@ import { FormulaError } from './FormulaError';
 import { IRange } from './IRange';
 import { IReferenceRange } from './IReferenceRange';
 import { IFunction } from './IFunction';
+import { IFunctionArguments } from './IFunctionArguments';
 import { IFormulaContext } from './IFormulaContext';
 import { IRuntime } from './IRuntime';
 import { LocaleProfile } from './LocaleProfile';
@@ -20,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 */
@@ -36,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 */
@@ -46,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 */
@@ -82,7 +89,7 @@ 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;
     /**
      * Parses the canonical English boolean and error literals.
      * See {@link IFormulaContext.parseAsLiteral}.
@@ -127,6 +134,8 @@ export declare class StubbedFormulaContext implements IFormulaContext {
     compare(a: Scalar, b: Scalar, options?: Intl.CollatorOptions): number;
     /** @inheritdoc IFormulaContext.getRuntime */
     getRuntime(): IRuntime;
+    /** @inheritdoc IFormulaContext.getArgs */
+    getArgs(): IFunctionArguments;
 }
 /**
  * The single, shared {@link IFormulaContext} that formula implementations use (via
@@ -144,6 +153,18 @@ export declare class ScopedFormulaContext implements IFormulaContext {
     _setScope(scope: Partial<IFormulaContext> | null): void;
     /** @hidden */
     _getScope(): Partial<IFormulaContext>;
+    /**
+     * @hidden Installed ONCE by the runtime marshaller; answers {@link getArgs} for whichever call
+     * is currently dispatching, or `null` when none is.
+     *
+     * @remarks
+     * A provider rather than a stack because the marshaller already pools one view per dispatch
+     * DEPTH and knows the current depth. Reading a function pointer costs nothing for the ~99% of
+     * calls whose body never asks.
+     */
+    protected _argsFn: (() => IFunctionArguments | null) | null;
+    /** @hidden */
+    _setArgsProvider(provider: (() => IFunctionArguments | null) | null): void;
     /** @inheritdoc IFormulaContext.getNumberFormat */
     getNumberFormat(formatText: string, value: Scalar): string | null;
     /** @inheritdoc IFormulaContext.getEntireCoords */
@@ -156,7 +177,7 @@ 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.parseAsLiteral */
     parseAsLiteral(text: string): boolean | FormulaError.Known | undefined;
     /** @inheritdoc IFormulaContext.toText */
@@ -173,12 +194,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 */
@@ -209,19 +236,23 @@ export declare class ScopedFormulaContext implements IFormulaContext {
     compare(a: Scalar, b: Scalar, options?: Intl.CollatorOptions): number;
     /** @inheritdoc IFormulaContext.getRuntime */
     getRuntime(): IRuntime;
+    /** @inheritdoc IFormulaContext.getArgs */
+    getArgs(): IFunctionArguments;
     get [Symbol.toStringTag](): string;
     toString(): string;
 }
 /**
  * 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

@@ -3,6 +3,7 @@ import { FormulaError } from './FormulaError';
 import { IRange } from './IRange';
 import { IReferenceRange } from './IReferenceRange';
 import { IFunction } from './IFunction';
+import { IFunctionArguments } from './IFunctionArguments';
 import { IRuntime } from './IRuntime';
 /**
  * Everything a formula function is allowed to know about the world outside its arguments.
@@ -27,9 +28,10 @@ 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` |
@@ -52,6 +54,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.
      *
@@ -92,6 +113,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}.
      *
@@ -275,6 +310,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
@@ -296,7 +332,7 @@ 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;
     /**
      * Reads a typed literal in the workbook's language — the parse side of {@link toText}.
      *
@@ -384,6 +420,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.
@@ -445,14 +505,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`
@@ -482,6 +540,22 @@ export interface IFormulaContext {
      * Mostly for diagnostics; the built-in `INFO` function is built on it.
      */
     getRuntime(): IRuntime;
+    /**
+     * The current call's arguments — how many the caller supplied, in which positions, of what kind,
+     * and what each value was BEFORE coercion.
+     *
+     * @remarks
+     * Argument REFLECTION, for the one thing a declaration cannot say: what happened at *this* call.
+     * It exists to serve Excel's declared `any`, which means "no contract, the body decides" — every
+     * other Excel type maps onto a type we already have and the marshaller handles it.
+     *
+     * The returned view is valid ONLY while the body that asked for it is running. Views are pooled
+     * by dispatch depth, so retaining one across an `await`, a callback, or a nested evaluation hands
+     * you another call's arguments.
+     *
+     * @throws If called outside a function dispatch — there are no arguments to reflect on.
+     */
+    getArgs(): IFunctionArguments;
 }
 /**
  * {@inheritDoc IFormulaContext}
@@ -505,6 +579,26 @@ 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';
+    }
     /**
      * A serial date split into fields — see {@link IFormulaContext.getDateParts}.
      *