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

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.
+     * 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).
      *
-     * 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.
-     *
-     * @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.
@@ -821,6 +903,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 +926,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 +1120,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 +1146,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.
      *
@@ -242,7 +256,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 +268,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 +451,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.
      */

package/types/src/Lazy.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Declares a parameter the engine may hand over UNEVALUATED — the argument's subtree is not run
+ * before the call, and it runs only if this call's answer needs it.
+ *
+ * @remarks
+ * An argument that is a bare reference has always been cheap to ignore: it resolves into a
+ * register and a body that never reads it never dereferences it. An argument that is an
+ * EXPRESSION is not — `IF(FALSE,B1+1,1)` evaluates `B1+1` before `IF` runs, so the untaken branch
+ * opens `B1` anyway. That is a correctness difference and not a cost one: a read is what decides
+ * a circular reference and what registers a volatile, so an arm nobody takes can report a cycle
+ * the sheet does not have.
+ *
+ * The marker is what closes it, and it is a CONTRACT rather than an inference. Nothing in
+ * JavaScript intercepts a plain parameter read, so a body holding a deferred value is only safe
+ * while it never touches it — which the declaration has to say out loud:
+ *
+ * ```ts
+ * export function IF(
+ *   logicalTest: boolean,
+ *   valueIfTrue: Lazy<AcceptError<any>>,
+ *   valueIfFalse: Lazy<AcceptError<any>, false>
+ * ): any {
+ *   return logicalTest ? valueIfTrue : valueIfFalse;
+ * }
+ * ```
+ *
+ * The parameter is ALWAYS an {@link ILazy} handle and never a union with the bare value, so the
+ * body has two things it may do with it and the type says which is which:
+ *
+ * - **return it unread**, which is what every branch-selecting function does. The engine
+ *   recognizes its own handle coming back as the call's result and evaluates that subtree then.
+ * - **read it** with {@link ILazy.getValue}, which forces the subtree in place. Synchronous only:
+ *   the engine is mid-formula there and has no way to wait, so an ASYNC subtree at a forced
+ *   handle is an error rather than a wrong answer.
+ *
+ * Only the RESULT positions are marked. A condition, an index and a case value are eager, which
+ * is what keeps `AND(FALSE,A1)` a circular reference: laziness is a property of what the function
+ * READS, not of the syntax around it.
+ *
+ * The engine may DECLINE to defer at any time and hand the body a handle that is already full —
+ * an absent argument, an async subtree, a lift that needs every arm anyway. `getValue()` then
+ * returns the value it was built with. The author cannot tell the two apart and must not try.
+ *
+ * @typeParam T - what the argument evaluates to; the marker is otherwise transparent.
+ * @typeParam V - what an ABSENT argument means, as a literal. It replaces the `= false`
+ *   initializer an ordinary parameter would carry, which cannot typecheck against a handle;
+ *   declaring it makes the parameter optional and the engine supplies the value, so the body
+ *   still sees nothing but a handle.
+ *
+ * @see {@link IFunction.ParameterTypeJSON.lazy}
+ */
+export type Lazy<T, V = never> = ILazy<T | V>;
+/**
+ * The handle a {@link Lazy} parameter receives: an argument's subtree, anchored at the calling
+ * cell, that has either not been evaluated yet or has been evaluated already.
+ *
+ * @remarks
+ * The brand exists for the same reason {@link Lambda}'s does — the value-layer sites (coercion,
+ * the operators, a range's typed read, a cell's final value) RECOGNIZE a handle and refuse it, so
+ * that one can never reach a grid, a spill or a named-formula result. A handle is only ever a
+ * live call's argument.
+ */
+export interface ILazy<T = any> {
+    /** The brand itself — the property every recognizing site reads. */
+    readonly isLazy: true;
+    /**
+     * Evaluates the argument and answers its value, forcing the subtree where the engine deferred
+     * it and answering the value it already has where it declined to.
+     *
+     * Forced at most once: a second call answers the same value.
+     */
+    getValue(): T;
+}
+/** `true` for a deferred-argument handle — see {@link ILazy}. */
+export declare const isLazyValue: (value: unknown) => value is ILazy;
+//# sourceMappingURL=Lazy.d.ts.map

package/types/src/NoFilter.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Declares that the members reaching a REPEATING scalar parameter are COERCED rather than
+ * filtered — one that cannot be coerced is `#VALUE!` for the whole call.
+ *
+ * The native functions FILTER: `SUM({1,"8",TRUE})` is 1, the text and the boolean skipped, and a
+ * blank cell contributes nothing. Excel's Analysis-ToolPak heritage coerces at the slot instead,
+ * and the difference is visible in both directions:
+ *
+ * | argument | native (`SUM`) | this marker (`GCD`) |
+ * | --- | --- | --- |
+ * | numeric text, `{6,"8",12}` | skipped | parses — `GCD({6,"8",12})` is 2 |
+ * | a boolean, `{6,TRUE,12}` | skipped | `#VALUE!` for the whole call |
+ * | a blank inside a multi-cell range | skipped | reads 0 — `LCM(6,A1:A2)` is 0 |
+ *
+ * A DIRECT argument follows the same rule (`GCD(6,TRUE,12)` is `#VALUE!` where `SUM(6,TRUE,12)`
+ * is 19). A one-cell blank reference and an omitted argument are still skipped either way: they
+ * never became members.
+ *
+ * Only a repeating slot has members to filter, so the marker means nothing on a plain scalar,
+ * range or lambda parameter and the linter refuses it there. It is the repeating counterpart of
+ * {@link NoLift}, which is the same heritage's reading of a NON-repeating scalar slot.
+ *
+ * It may be written over the group or on the slot — `NoFilter<number[]>` and `NoFilter<number>[]`
+ * mean the same thing, as they do for `AcceptError`.
+ *
+ * At the type level it is `T`.
+ *
+ * @example
+ * ```ts
+ * export function GCD(number: NoFilter<number>[]): number { ... }
+ * ```
+ */
+export type NoFilter<T> = T;
+//# sourceMappingURL=NoFilter.d.ts.map

package/types/src/NoLift.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Declares that a SCALAR parameter refuses a multi-cell REFERENCE with `#VALUE!` instead of
+ * broadcasting over it.
+ *
+ * The native functions lift: `ROUND(B1:B3,3)` spills three results. Excel's Analysis-ToolPak
+ * heritage refuses at the slot instead — `EDATE(A1:A3,1)` is `#VALUE!` — and the refusal is per
+ * PARAMETER: `NETWORKDAYS.INTL` refuses a reference at its two date slots and lifts one at its
+ * `weekend` slot. Three qualifications:
+ *
+ * | argument at the slot | answer |
+ * | --- | --- |
+ * | a multi-cell REFERENCE, `A1:A3` | `#VALUE!` — the call never runs |
+ * | an ARRAY, `{3,4,5}` | lifts as usual (`MROUND({3,4,5},5)` spills) |
+ * | a one-cell reference or a value | an ordinary argument |
+ *
+ * Only a scalar slot can lift, so the marker means nothing on a range, list or lambda parameter
+ * and the linter refuses it there. A REPEATING scalar slot is also never this marker's business —
+ * it absorbs a container as members whatever the function's heritage (`GCD(C1:C3)` is 4); its
+ * ATP reading is `NoFilter<T>`.
+ *
+ * At the type level it is `T`.
+ *
+ * @example
+ * ```ts
+ * export function NETWORKDAYS_INTL(
+ *   startDate: NoLift<Scalar>, endDate: NoLift<Scalar>, weekend?: Scalar, holidays?: Flatten<Scalar>
+ * ): number { ... }
+ * ```
+ */
+export type NoLift<T> = T;
+//# sourceMappingURL=NoLift.d.ts.map

package/types/src/Repeating.d.ts

@@ -48,19 +48,39 @@
  * "the final element of the final group may be omitted" rule; that rule would accept a formula
  * Excel refuses. An optional slot anywhere else in the group is a compiler error.
  *
+ * ### The maximum, `Max`
+ *
+ * The second type argument is the largest number of arguments the WHOLE CALL accepts, which is
+ * how Excel states it: one number per NAME, compared against the call's total argument count and
+ * refused at entry (`Excess_function_arguments`), never a count of this parameter's own share.
+ * `SWITCH`'s 254 therefore covers its `expression` and its trailing `default` as well as the
+ * pairs, and `CHOOSEROWS`' covers its `array`.
+ *
+ * It defaults to **255**, which is the ceiling for most names and the highest any name carries.
+ * Declare it only where a name draws the line lower — `XOR`, `IFS`, `SWITCH`, `LAMBDA`, `LET`,
+ * `AGGREGATE`, `SORTBY`, `MAXIFS`, `MINIFS`, `CONCAT`, `TEXTJOIN`, `HSTACK`, `VSTACK`,
+ * `CHOOSEROWS`, `CHOOSECOLS` and every DOTTED
+ * descriptive spelling (`STDEV.S`, `VAR.P`, `MODE.MULT`, …) all stop at 254 where their legacy
+ * twins take 255. It cannot be derived from the shape, so it belongs to the declaration.
+ *
+ * A REST parameter is the one place `Repeating` may be written alongside `...`, and only with an
+ * explicit `Max`: `...rest: Repeating<T, 254>` keeps the rest parameter's own 0-or-more meaning
+ * and adds nothing but the ceiling. A bare `Repeating<T>` on a rest parameter stays an error —
+ * that is the spelling collision the marker exists to avoid.
+ *
  * @example
  * ```ts
  * export function SUMIFS(
- *   sumRange: AcceptError<IRange>,
- *   criteria: Repeating<[criteriaRange: AcceptError<IReferenceRange>, criteria: AcceptError<IRange>]>
+ *   sumRange: IRange,
+ *   criteria: Repeating<[criteriaRange: IReferenceRange, criteria: AcceptError<Scalar>]>
  * ): IRange {
  *   for (const [range, test] of criteria) { ... }
  * }
  *
- * export function HSTACK(array: Repeating<AcceptError<IRange>>): IRange {
+ * export function HSTACK(array: Repeating<IRange, 254>): IRange {
  *   return array.reduce((acc, next) => acc.concat(next, IRange.Axis.Column));
  * }
  * ```
  */
-export type Repeating<T> = T[];
+export type Repeating<T, Max extends number = 255> = T[];
 //# sourceMappingURL=Repeating.d.ts.map

package/types/src/ReportType.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Declares the parameter's type as ADVISORY: the engine delivers it when it can, and hands the
+ * body whatever actually arrived when it cannot, instead of answering `#VALUE!` on the body's
+ * behalf.
+ *
+ * @remarks
+ * Excel has no marshalling contract. A function there is called with the operands as they are and
+ * calls library helpers for whatever it needs — `LARGE` asks for a range's values and gets every
+ * area of a union, `ROWS` never dereferences at all and answers `#REF!` when it sees two areas,
+ * `SUMPRODUCT` demands one rectangle and fails on the same argument. Three answers, no rule: the
+ * body's own access pattern is the whole of it.
+ *
+ * A declared surface cannot express that, and modelling it would mean a marker per behavior. This
+ * is the boundary instead — ONE marker saying "the type is what the caller is told, not a
+ * guarantee to the body". The declared `T` still reaches the function help, the wizard and the
+ * linter, because that IS what the slot means to a user; it just stops being a gate.
+ *
+ * | argument | plain `IRange` | `ReportType<IRange>` |
+ * | --- | --- | --- |
+ * | `A1:A5` | the range | the range |
+ * | `(A1:A5,B1:B2)` — a union | `#VALUE!`, the call never runs | the areas, as `IRange[]` |
+ * | a value, an error | `#VALUE!` / propagates | the value, the error |
+ *
+ * At the type level it is `T` — like {@link AcceptError}, and for the same reason: the marker is a
+ * RULE, not a type. A body that declares it and then assumes `T` will crash on the argument the
+ * marker exists to deliver, so narrow first. {@link IFunctionArguments.getKindAt} is total over
+ * what can arrive and {@link IFunctionArguments.getAreaCountAt} answers the union question the
+ * kind cannot — a plain reference is one area, a union is more.
+ *
+ * Its use is meant to stay countable: a slot earns it with a rule Excel actually shows, never
+ * with a guess.
+ *
+ * @example
+ * ```ts
+ * export function ROWS(array: ReportType<IRange>): Scalar {
+ *   if (FormulaContext.getArgs().getAreaCountAt(0) > 1) return FormulaError.BuiltIn.Ref!;
+ *   return array.getRowCount();
+ * }
+ * ```
+ */
+export type ReportType<T> = T;
+//# sourceMappingURL=ReportType.d.ts.map

package/types/src/Scalar.d.ts

@@ -42,7 +42,7 @@ export declare namespace Scalar {
      * text's shape (decimal places, grouping) survives for format inference.
      *
      * @remarks
-     * Callers apply this to every text→number path and to nothing else — measured
+     * Callers apply this to every text→number path and to nothing else. It is
      * truncation, not rounding: `1234567890.123456789` stores `…345`, never `…346`.
      */
     function truncateNumberText(text: string): string;