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

package/types/src/IFunctionArguments.d.ts

@@ -0,0 +1,214 @@
+import { Scalar } from './Scalar';
+import { ValueKind } from './ValueKind';
+import { IRange } from './IRange';
+import { Lambda } from './Lambda';
+import { IFunction } from './IFunction';
+/**
+ * The current call's arguments, as the body sees them — argument **reflection**.
+ *
+ * @remarks
+ * A declaration answers "what does this parameter mean?", and the marshaller coerces every
+ * argument to it. That is right for the overwhelming majority of parameters. What it cannot answer
+ * is anything about *this particular call*:
+ *
+ * - What did the caller write there — a value, a cell, an array, nothing at all?
+ * - What was the value BEFORE the parameter's type coerced it?
+ * - Was that empty slot an omission, or a blank cell the caller pointed at?
+ *
+ * Excel has behaviors that turn on exactly those questions, and they cluster at the
+ * parameters Excel declares `any` — where there is nothing to express as a type, because Excel
+ * declined to express one. `CUMIPMT` refuses a boolean at every slot while `FV` coerces one at
+ * every slot; the difference is not the values, it is that `CUMIPMT`'s slots are `any` and its
+ * body decides.
+ *
+ * It is REFLECTION and nothing else — two questions, and no third:
+ *
+ * | question | answers |
+ * | --- | --- |
+ * | *what was supplied* | {@link getLength}, {@link getKindAt} |
+ * | *what it is* | {@link getRawAt}, {@link getKindAt} |
+ *
+ * Coercion is deliberately absent. A body that wants a number calls
+ * {@link IFormulaContext.parseAsNumber} on the value this hands it — that already takes a value,
+ * already propagates an incoming error with its identity, and already answers `#VALUE!` for a
+ * boolean, which IS the rule an `any` slot needs. There is no coercion an index can do that a
+ * value cannot.
+ *
+ * Obtained from `FormulaContext.getArgs()`, and valid ONLY while the body that asked for it is
+ * running. A body must not retain it across an `await`, a callback, or a nested evaluation — the
+ * views are pooled by dispatch depth, so the one at your depth is handed to the next call at that
+ * depth.
+ *
+ * ```typescript
+ * export function CUMIPMT(rate: Scalar, nper: Scalar): number {
+ *   const args = FormulaContext.getArgs();
+ *   if (args.getKindAt(0) === ValueKind.Omitted) return FormulaError.BuiltIn.NA; // `CUMIPMT(,120,…)`
+ *   const asNumber = FormulaContext.parseAsNumber(args.getRawAt(0) as Scalar);  // TRUE is #VALUE!
+ *   // …
+ * }
+ * ```
+ *
+ * @see {@link IFormulaContext.getArgs}
+ */
+export interface IFunctionArguments {
+    /**
+     * How many PARAMETERS the caller supplied.
+     *
+     * @remarks
+     * Indexing throughout matches the BODY's own signature, never the raw call positions
+     * (see {@link getRawAt}). `index >= getLength()` is an ABSENT argument — one the caller never
+     * wrote, whose own JS initializer supplied the value. That is a different thing from an OMITTED
+     * one; see {@link isOmittedAt}.
+     */
+    getLength(): number;
+    /**
+     * This invocation's value at `index`, uncoerced.
+     *
+     * @param index The PARAMETER index — the position in the body's own signature.
+     *
+     * @remarks
+     * A `Scalar` means the argument IS a value; an {@link IRange} means a container whose members
+     * the body reads itself (a reference materializes on demand); a {@link Lambda} means a callable.
+     *
+     * At a REPEATING parameter (`Repeating<T>`, or a rest parameter) this is the ARRAY of that
+     * group's values — one entry per argument the caller wrote — and {@link getRepeatingArgsAt} is the
+     * per-argument view of the same thing. Indexing by parameter rather than by call position is
+     * what lets a body ask its questions in the vocabulary it declared:
+     *
+     * ```typescript
+     * // IFS(condition: Repeating<[logicalTest: boolean, logicalTrue: AcceptError<any>]>)
+     * args.getRawAt(0);                       // [test1, value1, test2, value2, …]
+     * args.getRepeatingArgsAt(0).getRawAt(0);     // test1
+     * ```
+     *
+     * **Under a lift** the call broadcasts and the body runs once per output cell; this reports the
+     * value for THIS invocation — the member at the current broadcast position for a lifted argument,
+     * the whole argument for one that is not lifting. That is what every identified caller wants: a
+     * body checking for a boolean must see the member, not the array around it.
+     *
+     * One boundary is worth knowing: under a lift at a parameter that declares a CONCRETE scalar
+     * type, the member has already been converted by that declaration, so the raw and coerced answers
+     * coincide there. At the `Scalar` slots this interface exists for, nothing coerces and the value
+     * is the member exactly as the caller's range holds it.
+     *
+     * A reference UNION (`(A1:A3,C1:C3)`) is an array too — one `IReferenceRange` per area — which
+     * is how a body whose slot took the areas apart can still tell one argument's union from two
+     * arguments (`SUMPRODUCT` refuses the first and accepts the second).
+     */
+    getRawAt(index: number): IFunctionArguments.RawArg | IFunctionArguments.RawArg[];
+    /**
+     * A nested view over one REPEATING parameter's arguments, so a body can ask the same questions
+     * one level down — `getRepeatingArgsAt(0).isOmittedAt(1)`.
+     *
+     * @param index The PARAMETER index of the repeating group (or rest parameter).
+     *
+     * @remarks
+     * The nested view is FLAT over the group's arguments: a period-2 group repeated three times reads
+     * as six, in call order. That is where "which one was omitted" has an answer at all — the group
+     * as a whole cannot be omitted, only one of its arguments can.
+     *
+     * At a non-repeating parameter this returns an EMPTY view (`getLength()` of 0) rather than
+     * throwing, so a body that folds over its groups needs no special case.
+     */
+    getRepeatingArgsAt(index: number): IFunctionArguments;
+    /**
+     * The KIND of the argument at `index` — the total discriminator over {@link getRawAt}'s value.
+     *
+     * @param index The PARAMETER index — the position in the body's own signature.
+     *
+     * @remarks
+     * Every raw argument is exactly one of a closed set of kinds ({@link ValueKind}), and this
+     * answers without materializing anything — a reference stays coords underneath. The scalar
+     * kinds ARE `ScalarType` values, so `getKindAt(i) === ScalarType.Boolean` reads naturally.
+     *
+     * Under a lift this reports THIS invocation's value, like {@link getRawAt} — except the
+     * {@link ValueKind.Omitted} answer, which is a fact about the CALL (the caller wrote an empty
+     * comma) and does not change per broadcast position. At a REPEATING parameter it answers for
+     * the group's FIRST argument; per-argument kinds are one level down —
+     * `getRepeatingArgsAt(i).getKindAt(j)`.
+     *
+     * There are THREE argument positions:
+     *
+     * | form | position | answer |
+     * | --- | --- | --- |
+     * | `CUMIPMT(0.01,120,100000,13,24)` | never wrote a 6th | `Omitted` here — the POSITION fact is {@link getLength} (`index >= getLength()`), not a kind |
+     * | `CUMIPMT(,120,100000,13,24,0)` | the empty comma | {@link ValueKind.Omitted} |
+     * | `CUMIPMT(…,E1)`, E1 blank | a blank CELL | {@link ValueKind.Reference} — blankness is the cell's value, not the argument |
+     *
+     * The kind is the argument's own and it survives what it passes through:
+     * `VLOOKUP(10,10,1,TRUE)` is `#N/A` where `VLOOKUP(10,{10},1,TRUE)` is 10 — scalar vs 1x1
+     * array; `TYPE(IF(TRUE,10))` is 1 where `TYPE(IF(TRUE,{10}))` is 64 — a selector carries the
+     * kind through in both directions.
+     */
+    getKindAt(index: number): ValueKind;
+    /**
+     * True when the argument at `index` is DIRECT — Excel's "typed into the list of arguments":
+     * the evaluated value IS a value, not a container or a callable.
+     *
+     * @param index The PARAMETER index — the position in the body's own signature.
+     *
+     * @remarks
+     * The derived predicate over {@link getKindAt}: true exactly when the kind is one of the
+     * `ScalarType` members. A blank (`ScalarType.Null`) IS a value and is direct; an omitted
+     * argument, a reference, an array and a callable are not. Directness is what the
+     * direct-vs-member coercion rules key on (`SUM(1,TRUE)` is 2 where `SUM({1,TRUE})` is 1), so
+     * a body speaking that vocabulary can ask in it.
+     */
+    isDirectAt(index: number): boolean;
+    /**
+     * How many AREAS the argument at `index` covers — 1 for an ordinary reference, more for a
+     * union (`(A1:A5,B1:B2)`), and 0 for anything that is not a reference at all.
+     *
+     * @param index The PARAMETER index — the position in the body's own signature.
+     *
+     * @remarks
+     * {@link getKindAt} deliberately cannot answer this: a union IS a reference and reports
+     * {@link ValueKind.Reference}, the same as `A1:A5`. This is the question a body asks when the
+     * union is the thing it must decide about, and the three possible answers all come from asking
+     * it — flatten every area, refuse, or `#REF!`.
+     *
+     * Only a {@link IFunction.ParameterTypeJSON.reportType} slot can see a union at all; at every
+     * other slot the marshaller has already answered `#VALUE!`.
+     */
+    getAreaCountAt(index: number): number;
+    /**
+     * The functions the argument at `index` holds, in row-major order — or `null` unless it holds
+     * nothing but functions.
+     *
+     * @param index The PARAMETER index — the position in the body's own signature.
+     *
+     * @remarks
+     * A formula can pass a function as a value: `LAMBDA(x, x * 2)`, or a built-in by name, as `SUM`
+     * is in `BYROW(A1:C3, SUM)`. A `Lambda` parameter takes ONE such value. This is for an untyped
+     * parameter that also takes an ARRAY of them, as `HSTACK(SUM, AVERAGE)` makes.
+     *
+     * The argument's shape is its own: {@link getKindAt} is `Lambda` for one function and `Array`
+     * for several, and {@link getRawAt} is that array. A function value IS an {@link IFunction}: a
+     * built-in by name answers as the registry's function does, and a `LAMBDA` is one whose
+     * {@link IFunction.isLambda} is `true`. A body whose untyped parameter holds the value reads the
+     * functions from it directly; this is reflection, for when the declaration does not hand it over.
+     *
+     * Nothing is collected until every member has proved to be a function, so a data range given by
+     * mistake costs one member.
+     */
+    getFunctionsAt(index: number): readonly IFunction[] | null;
+}
+/**
+ * {@inheritDoc IFunctionArguments}
+ *
+ * @see
+ * ### **Interface**
+ *
+ * {@link IFunctionArguments}
+ */
+export declare namespace IFunctionArguments {
+    /**
+     * One argument as the caller wrote it — a value, a container, a callable, or nothing.
+     *
+     * @remarks
+     * `undefined` is an OMITTED or ABSENT argument; `null` is a blank, which is a value. A reference
+     * union is delivered as `RawArg[]` — one reference per area (see {@link IFunctionArguments.getRawAt}).
+     */
+    type RawArg = Scalar | IRange | Lambda | undefined;
+}
+//# sourceMappingURL=IFunctionArguments.d.ts.map

package/types/src/IRange.d.ts

@@ -69,11 +69,16 @@ export interface IRange<T extends Scalar = Scalar> {
     uniqueIndices(axis?: IRange.Axis, exactlyOnce?: boolean): number[];
     /**
      * Applies a callback function to elements from this range and another range or a scalar,
-     * using NumPy-style broadcasting.
+     * using Excel's broadcasting rules. This is the two-operand special case of {@link zip}:
+     * `a.broadcast(b, f)` is `a.zip([b], ([x, y]) => f(x, y))`.
      *
-     * **Broadcasting Rules:**
-     * - If `other` is a scalar, it is broadcasted to match the shape of this range.
-     * - If `other` is a range, both ranges must have the same length.
+     * **Broadcasting Rules** (the same as {@link zip}):
+     * - A scalar or a 1×1 range fills any shape: (1×1) + (3×4) → (3×4)
+     * - Same shapes pair position by position: (3×4) + (3×4) → (3×4)
+     * - A dimension of 1 tiles across the other operand's: (3×1) + (3×4) → (3×4)
+     * - Incompatible shapes (neither equal nor 1) throw, unless `misalignValue` is set, in which
+     *   case the result is the union shape and every position outside the intersection holds
+     *   `misalignValue`. Here the pad is a RESULT; in {@link zip} it is an ARGUMENT.
      *
      * @param other The other range or scalar to broadcast with.
      * @param callbackFn The function to apply to corresponding elements.
@@ -82,11 +87,10 @@ export interface IRange<T extends Scalar = Scalar> {
      * @returns A new range with the broadcasted results.
      *
      * @remarks
-     * Broadcasting rules (NumPy-style):
-     * - Scalar broadcasts to any shape: (1×1) + (3×4) → (3×4)
-     * - Same shapes work: (3×4) + (3×4) → (3×4)
-     * - Trailing dimensions of 1 broadcast: (3×1) + (3×4) → (3×4)
-     * - Incompatible shapes error: (3×4) + (2×3) → Error (unless misalignValue set)
+     * Iteration is sparse: the positions visited are the union of both operands' stored cells. A
+     * position empty on both sides has one answer, and a callback that reads only its two values
+     * (`callbackFn.length === 2`) receives that answer computed ONCE and written as runs; a callback
+     * that asks for `coords` or `range` is called per position instead.
      */
     broadcast<TS extends Scalar = T>(other: IRange | TS, callbackFn: (a: TS, b: TS, coords: IRange.CellCoords, range: IRange<T>) => TS, options?: IRange.BroadcastOptions): this;
     /**
@@ -244,11 +248,40 @@ export interface IRange<T extends Scalar = Scalar> {
      */
     filter<TS extends Scalar = T>(callbackFn: (value: TS, coords: IRange.CellCoords, range: IRange<T>) => MaybeError<boolean>, options?: IRange.TraversalAxis | IRange.IteratorOptions): this;
     /**
-     * Returns the values as an array of values.
+     * The first error member in row-major order, or `null` when there is none — the identity that
+     * propagates when a body refuses a range with an error inside it:
+     * `if (range.hasError()) return range.firstError();`.
+     *
+     * @remarks
+     * Errors INSIDE a range are the body's to judge: the engine hands a valid range over whole and
+     * never looks inside, so a function whose answer depends on every member says so with this
+     * line, placed before its own validation where Excel's error outranks it. A reshaper or a
+     * lookup, whose members pass through or are never read, needs no line at all.
+     */
+    firstError(): FormulaError.Known | null;
+    /**
+     * Linearizes the range into a single column by flattened ordinal — the member at ordinal `i`
+     * lands at row `i`, column 0.
      *
      * @param options {@link IRange.IteratorOptions}
+     *
+     * @remarks
+     * `options.axis` is the TRAVERSAL order feeding the ordinal, not the orientation of the result:
+     * the result is always Nx1, and a row is `flatten().transpose()`. The default is row-major,
+     * which is the order Excel pairs two range operands in.
+     *
+     * `options.type` carries a read type onto the result, so a member the type filters out becomes
+     * a HOLE at its ordinal rather than compacting the column. That is what lets two operands be
+     * paired position by position — see {@link alignValues}.
+     *
+     * `options.includeEmpty` has no meaning here and is ignored: a range is inherently sparse, so
+     * an empty position is simply absent. Sparsity is preserved and nothing is materialized.
+     *
+     * Equivalent to `reshape(rows * columns, 1)`, which is where the ordinal rule is stated.
+     *
+     * @see {@link getValuesFlat} for the same linearization as a JS array.
      */
-    flatten<TS extends Scalar = T>(options?: IRange.IteratorOptions): TS[];
+    flatten(options?: IRange.IteratorOptions): this;
     /**
      * Iterates over the cells within the range, applying the provided callback function to each cell.
      *
@@ -326,6 +359,30 @@ export interface IRange<T extends Scalar = Scalar> {
      * @param options {@link IRange.ValueOptions}
      */
     getValueAt<TS extends Scalar = T>(rowIndex: number, colIndex: number, options?: IRange.ValueOptions): TS;
+    /**
+     * Returns the members as a flat JS array.
+     *
+     * @param options {@link IRange.IteratorOptions}
+     *
+     * @remarks
+     * The array form of {@link flatten}. Skips empty members unless `includeEmpty` is set, where
+     * `flatten` keeps them as holes in a range.
+     */
+    getValuesFlat<TS extends Scalar = T>(options?: IRange.IteratorOptions): TS[];
+    /**
+     * Returns the position of the first member equal to `value`, or `-1` when there is none.
+     *
+     * @param value The value to find.
+     * @param options {@link IRange.IndexOfOptions}
+     *
+     * @remarks
+     * Equality is the `=` operator's: text is case-insensitive, and no value matches one of another
+     * type (`1` does not match `"1"`, nor `TRUE` `1`). Empty members, errors and rich data are never
+     * a match. The position is the offset along a row or column vector, and the row-major offset
+     * within a larger range. This is `MATCH(value, range, 0)` less one, and a range read by many
+     * lookups is indexed once rather than scanned per call.
+     */
+    indexOf(value: Scalar, options?: IRange.IndexOfOptions): number;
     /**
      * Returns the number of columns of the range.
      */
@@ -345,7 +402,7 @@ export interface IRange<T extends Scalar = Scalar> {
      * outputs and `map` cannot know what type they are. Use {@link IRange.toType} on the result if
      * you do know. (`options.type` still applies to the values handed TO the callback.)
      */
-    map<TS extends Scalar = T>(callbackFn: (value: TS, coords: IRange.CellCoords, range: IRange<T>) => TS, options?: IRange.IteratorOptions): this;
+    map<TS extends Scalar = T>(callbackFn: (value: TS, coords: IRange.CellCoords, range: IRange<T>) => TS, options?: IRange.MapOptions): this;
     /**
      * Returns a new range where each cell is replaced with the value from `ifTrues`
      * where the corresponding `conditions` value is strictly `true`.
@@ -602,40 +659,54 @@ export interface IRange<T extends Scalar = Scalar> {
      */
     values<TS extends Scalar = T>(options?: IRange.IteratorOptions): IterableIterator<TS>;
     /**
-     * Iterates over this range and one or more other ranges or scalars in lockstep,
-     * calling the provided function with the broadcast-resolved values at each position,
-     * and returns a new range containing the results.
-     *
-     * Broadcast semantics follow Excel conventions:
-     * - A 1×1 scalar or range broadcasts to fill any shape.
-     * - A 1×N or N×1 range broadcasts to fill the missing dimension.
-     * - Ranges with incompatible shapes produce a `#VALUE!` error.
+     * Aligns this range with any number of other ranges or scalars under Excel's broadcasting
+     * rules, calls `callbackFn` with the aligned values at each position, and returns the results as
+     * a new range of the broadcast shape. This is the N-ary form of {@link broadcast}, and the numpy
+     * idiom "align once, apply the kernel, never index"
+     * (`np.frompyfunc(f, n, 1)(*np.broadcast_arrays(...))`).
+     *
+     * **Broadcasting Rules** (Excel's; {@link broadcast} shares them):
+     * - A scalar or a 1×1 range FILLS: it is the same value at every position.
+     * - A dimension of 1 TILES across the largest extent in that dimension (`tile`, default on).
+     * - A shorter dimension PADS: past its extent the operand contributes `misalignValue`
+     *   (default `#N/A`). The pad is an ARGUMENT, reaching the callback in that operand's slot for
+     *   the callback to decide what it means; it is not a result written around the callback.
+     * - The output is `max(rows)` × `max(cols)` over the operands, anchored at this range's origin.
+     *
+     * **Iteration is sparse.** The positions visited are the UNION of the operands' stored cells
+     * after broadcast mapping; an operand with no cell at a visited position contributes its empty
+     * value (`null`, or the empty of `type`). Where EVERY shaped operand is blank the answer depends
+     * only on which operands are padded there, so those positions form REGIONS of equal padding,
+     * one per combination of operand extents, and `blankRegions` says how they are answered:
+     * `'each'` (default) calls the callback per position with its coordinates; `'once'` calls it once
+     * per region (the pandas `SparseArray` rule: the kernel runs once on `fill_value` and per stored
+     * entry otherwise) — the unpadded region's answer is what the result's empty positions read as,
+     * a padded region is written as runs. A region call carries `coords` of
+     * `{ rowIndex: -1, colIndex: -1 }`: it answers for many positions and no one of them. Under
+     * `'once'` a stretch of stored positions holding one value across every operand is one call too.
+     * An operand's own empty positions read as its empty value (a `fillEmpty`, an earlier
+     * elementwise result) and are never visited one by one.
+     *
+     * @param others Additional ranges or scalar values to align with this range, in argument order.
+     * @param callbackFn Called at each position with the aligned values (`values[0]` is this
+     *   range's, `values[i + 1]` is `others[i]`'s), the position relative to the output, and this
+     *   range. Returns the output value for that position. `values` is ONE buffer reused across
+     *   calls (the ufunc inner-loop rule): read it, do not retain it.
+     * @param options {@link IRange.ZipOptions}. `type` reads EVERY operand's members, and the
+     *   empty, through that type; it defaults to this range's own type, as {@link broadcast} does.
+     *   Pass `type: null` to read every operand raw.
+     * @returns A new, untyped range of the broadcast shape (the values are the callback's, so this
+     *   range's type does not describe them).
      *
-     * @param others Additional ranges or scalar values to zip with this range.
-     * @param callbackFn Called at each position with the broadcast-resolved values from
-     *   all ranges (`values[0]` is from `this`, `values[1]` onward are from `others`),
-     *   the current cell coordinates, and the original range. Returns the output value
-     *   for that position.
-     * @param options {@link IRange.IteratorOptions}
-     * @returns A new range of the same shape as the broadcast result.
+     * @example
+     * // A 3×1 beside a 1×3 is 3×3: rows tile from the first, columns from the second.
+     * const sums = a.zip([b, 10], ([x, y, k]) => (x as number) + (y as number) + (k as number));
      */
-    zip(others: (IRange | Scalar)[], callbackFn: (values: Scalar[], coords: IRange.CellCoords, range: IRange<T>) => Scalar, options?: IRange.IteratorOptions): this;
+    zip(others: (IRange | Scalar)[], callbackFn: (values: Scalar[], coords: IRange.CellCoords, range: IRange<T>) => Scalar, options?: IRange.ZipOptions): this;
     /**
      * Returns a string representation of the range.
      */
     toString(): string;
-    /**
-     * Returns `true` if the range is a literal range from a parameter.
-     */
-    isLiteral(): boolean;
-    /**
-     * Returns `true` if the range is a scalar.
-     */
-    isScalar(): boolean;
-    /**
-     * Returns `true` if the range is a vector (1D) either row or column.
-     */
-    isVector(): boolean;
     /**
      * Returns `true` if the range is empty.
      */
@@ -668,6 +739,17 @@ export declare namespace IRange {
     /**
      * Options for controlling iteration behavior.
      */
+    /**
+     * Options for {@link IRange.indexOf}.
+     */
+    interface IndexOfOptions {
+        /**
+         * Search from the last member back, answering the last match.
+         *
+         * @defaultValue `false`
+         */
+        reverse?: boolean;
+    }
     interface IteratorOptions extends IRange.ValueOptions {
         /**
          * The direction of the iteration.
@@ -705,6 +787,24 @@ export declare namespace IRange {
          * If passing a large bound care must be taken.
          */
         includeEmpty?: boolean;
+        /**
+         * Skips rows of the range: given the next row that would be read, answers the row to read
+         * instead - the same row when it is read, or the next one that is (the previous, when
+         * `reverse`).
+         *
+         * @param index The 0-based row about to be read.
+         * @param reverse Whether the read runs from the last row back.
+         * @returns The row to read, at or past `index`.
+         *
+         * @remarks
+         * A skipped cell is not visited, reads as empty and is left out of the statistics; the shape
+         * of the range is unchanged. `SUBTOTAL` reads a range this way when it skips hidden rows.
+         */
+        processRowSkip?: (index: number, reverse?: boolean) => number;
+        /**
+         * Skips columns of the range, as {@link processRowSkip} skips rows.
+         */
+        processColumnSkip?: (index: number, reverse?: boolean) => number;
         /**
          * Useful for callback functions that want a this.
          */
@@ -821,6 +921,8 @@ export declare namespace IRange {
          *   - It expands the result to the **union of both range sizes**.
          *   - Any cells that do not have valid corresponding values from the inputs
          *     will be filled with `misalignValue` instead of causing an error.
+         * - `zip()`, `mask()` and `choose()` always pad and default it to `#N/A`; in `zip()` the pad
+         *   is delivered to the callback as that operand's value rather than written as the result.
          *
          * @example
          * // Throws an error if A and B are not naturally broadcast-compatible
@@ -842,6 +944,53 @@ export declare namespace IRange {
          */
         otherType?: ScalarType;
     }
+    /**
+     * Options for {@link IRange.map}.
+     */
+    interface MapOptions extends IRange.IteratorOptions {
+        /**
+         * How the positions the range does not store are answered.
+         *
+         * @defaultValue `'each'`
+         *
+         * @remarks
+         * `'each'` is the sparse walk: an empty position is not visited (or, with `includeEmpty`,
+         * visited with its coordinates). `'once'` calls the callback a single time for every empty
+         * position, with `coords` of `{ rowIndex: -1, colIndex: -1 }` and the value an empty reads
+         * as, and every one of them takes that answer — the {@link IRange.zip} rule. Under `'once'` a
+         * stretch of stored positions holding one value is also one call; a callback that reads only
+         * its value gets that on its own (it cannot tell), and one that reads `coords` opts in here.
+         */
+        blankRegions?: 'each' | 'once';
+    }
+    /**
+     * Options for {@link IRange.zip}.
+     */
+    interface ZipOptions extends IRange.ValuesOptions {
+        /**
+         * Whether a dimension of 1 tiles across the largest extent in that dimension.
+         *
+         * @defaultValue `true`
+         *
+         * @remarks
+         * Off, a dimension of 1 is a short dimension like any other and pads `misalignValue` past
+         * its one position: Excel's `MAP` rule, where a 1-row array is not stretched.
+         */
+        tile?: boolean;
+        /**
+         * How the positions where EVERY shaped operand is blank are answered.
+         *
+         * @defaultValue `'each'`
+         *
+         * @remarks
+         * Such positions form regions of equal padding (see {@link IRange.zip}). `'each'` visits every
+         * one with its coordinates; `'once'` calls the callback a single time per region, with
+         * `coords` of `{ rowIndex: -1, colIndex: -1 }`, and writes the region as runs. An explicit
+         * option rather than a callback-arity gate, so a callback that reads `coords` for the positions
+         * it IS given can still have the blanks answered in one call.
+         */
+        blankRegions?: 'each' | 'once';
+    }
     /**
      * Options used during masking.
      */
@@ -989,6 +1138,15 @@ export declare namespace IRange {
         rowEnd: number;
         /**
          * An optional identifier for the 2D space these coordinates are relative to.
+         *
+         * @remarks
+         * `scope` was added after the coords reuse/scratch patterns were established, so it is the
+         * field a reused object is most likely to carry STALE. The contract: a function that writes
+         * its result into a caller-supplied reuse object must write `scope` unconditionally —
+         * `null` when the result is unscoped, never left over from the previous occupant
+         * (a leaked scope silently re-targets the coords at another sheet's grid). Writing it
+         * conditionally is only safe on a freshly created object. Geometry-only helpers that
+         * never read or write `scope` (CoordUtils) are exempt; their scope-aware wrappers own it.
          */
         scope?: string | null;
     }
@@ -1006,6 +1164,7 @@ export declare namespace IRange {
         rowIndex: number;
         /**
          * An optional identifier for the 2D space these coordinates are relative to.
+         * See the remark on {@link Coords.scope} for the reuse-object contract.
          */
         scope?: string | null;
     }

package/types/src/IRangeStats.d.ts

@@ -19,6 +19,20 @@ import { FormulaError } from './FormulaError';
  * 5. Quick introspection without triggering a full range scan
  */
 export interface IRangeStats {
+    /**
+     * Returns the bounding box of the cells these stats cover, in the coordinates of the scanned
+     * grid.
+     *
+     * @returns The smallest rectangle containing every covered coordinate, or `null` when the
+     * stats cover nothing.
+     *
+     * @remarks
+     * Stats over several areas (a multi-area range, or a composite over several ranges) return the
+     * union box, which can include cells outside every area — and a composite's children may sit
+     * on different sheets, so its box is a shape, not an address. `getSize()` is the exact cell
+     * count; this is where those cells are.
+     */
+    getCoords(): IRange.Coords | null;
     /**
      * Returns the total number of cells in the range, including empty cells.
      *
@@ -146,7 +160,8 @@ export interface IRangeStats {
      *
      * - Every requested type (all types when omitted) is present with an explicit count —
      *   a `0` is a fact about the range, a missing key would be ambiguous.
-     * - Blanks report under {@link ScalarType.Null}: total cells minus non-empty values.
+     * - Blanks report under {@link ScalarType.Null}: total cells minus non-empty values. A cell the
+     *   range skips ({@link IRange.IteratorOptions.processRowSkip}) is not a blank; it is not counted.
      * - Never throws on error values — errors are population here, not faults — regardless of
      *   the `onError` iterator policy the stats were created with.
      */
@@ -242,7 +257,9 @@ export declare namespace IRangeStats {
         /**
          * Returns the k-th largest numeric value (1-based).
          *
-         * @param k The rank of the value to return, where 1 is the largest value. Must be a positive integer.
+         * @param k The rank of the value to return, where 1 is the largest value. A fractional rank
+         *          becomes a 0-based index before it truncates — over five values `k = 2.5` is the
+         *          THIRD largest, not the second.
          * @returns `null` if k is out of range.
          *
          * @remarks
@@ -252,7 +269,8 @@ export declare namespace IRangeStats {
         /**
          * Returns the k-th smallest numeric value (1-based).
          *
-         * @param k The rank of the value to return, where 1 is the smallest value. Must be a positive integer.
+         * @param k The rank of the value to return, where 1 is the smallest value. A fractional rank
+         *          becomes a 0-based index before it truncates.
          * @returns `null` if k is out of range.
          *
          * @remarks
@@ -434,6 +452,19 @@ export declare namespace IRangeStats {
          * This is a convenience method (visitedCount < totalCount)
          */
         isTruncated(): boolean;
+        /**
+         * Returns the bounding box of a value's occurrences, in the coordinates of the scanned grid.
+         *
+         * @param value The value to look up
+         * @returns The smallest rectangle containing every occurrence, or `null` when the value was
+         * not found, is blank, or the frequencies were merged from several ranges (no single grid).
+         *
+         * @remarks
+         * Tracked by the same scan that counts, so it costs nothing extra. A box whose cell count
+         * equals {@link getFrequency} is a contiguous block — the value lives in exactly that
+         * rectangle; a larger box means the occurrences are scattered within it.
+         */
+        getExtent(value: Scalar): IRange.Coords | null;
     }
     /**
      * Options for finding top values in a range.

package/types/src/IRuntime.d.ts

@@ -54,9 +54,32 @@ export interface IRuntime {
      */
     getOS(): string;
     /**
-     * Returns the current timestamp as a serialized number.
+     * Returns the clock this runtime reads, as epoch milliseconds.
+     *
+     * @remarks
+     * A workbook's own runtime answers the current commit's timestamp, so every cell of a
+     * calculation pass agrees and collaborators on that commit agree with each other. A runtime
+     * built by a host answers whatever that host supplied — a pinned clock makes `NOW` and `TODAY`
+     * reproducible, and an unpinned one is the wall clock, which advances between reads.
      */
     getNow: () => number;
+    /**
+     * Returns a random number in `[0, 1)` — one per calculation pass, as {@link getNow} is one
+     * clock reading per pass.
+     *
+     * @remarks
+     * This is not a cell's value. Each cell's draw is derived from this one, its position and which
+     * draw it is within that cell, so cells that do not depend on each other — which the engine is
+     * free to evaluate in any order — get the values their positions earn rather than the values
+     * their turn earned.
+     *
+     * Pinning it therefore pins `RAND`, `RANDBETWEEN` and `RANDARRAY`, exactly as pinning
+     * {@link getNow} pins `NOW` and `TODAY`. Left alone it is `Math.random`, drawn afresh each pass,
+     * so volatiles move on every recalculation.
+     *
+     * Values reproduce within one release, not across releases.
+     */
+    getRandom: () => number;
     /**
      * Returns the current user or `null` if no user information is provided.
      */