@sheetxl/primitives 0.7.22 → 0.7.23-beta.1

package/types/src/IRange.d.ts

@@ -0,0 +1,1091 @@
+import { ScalarType } from './ScalarType';
+import { Scalar } from './Scalar';
+import { FormulaError, MaybeError } from './FormulaError';
+import { IRangeStats } from './IRangeStats';
+/**
+ * An immutable two-dimensional, mixed-type sparse array with functional vector semantics.
+ *
+ * @remarks
+ * IRange is a persistent data structure — all operations return new ranges
+ * via structural sharing. This allows for zero-copy cache-friendly writes, SIMD optimized
+ * reads, and lockless concurrent evaluation.
+ *
+ * Designed to ensure familiarity for NumPy and JAX-ML users.
+ *
+ * 5 primitives are the core methods that have direct access to internal state.
+ *
+ * - entries()                — iterator with sparse/dense, axis, direction, and coercible options.
+ * - sparseBuilder()          — streaming writer for sparse output construction.
+ * - getShape()               — returns { rows, columns }.
+ * - resize()                 — returns a new IRange at a different shape with a fill value.
+ * - getType()                — the scalar type used for default coercion if set.
+ *
+ * 6 additional methods have been highly optimized for performance.
+ *
+ * - getValueAt(row, column)  — fast random access to individual cells.
+ * - fill()                   — smart vector compression, zero copy.
+ * - fillEmpty()              — virtual update for empty.
+ * - clone()                  — creates a deep copy of the range.
+ * - getStats()               — returns range statistics.
+ * - hasError()               — exact error-member existence, raw untyped read.
+ *
+ * `errors()` is composed from the primitives but may be accelerated by implementations.
+ *
+ * All other methods — including `mask`, `choose`, `select`, `tile`, `repeat`, and the rest of the
+ * utility surface are composed entirely in terms of those primitives with no special internal access.
+ */
+export interface IRange<T extends Scalar = Scalar> {
+    /**
+     * Returns the permutation indices that would sort the range.
+     * Analogous to `np.argsort`. Use with `take()` to sort a parallel range (SORTBY pattern).
+     *
+     * @example
+     * // single key
+     * const perm = keyRange.argsort(1);
+     * return dataRange.take(perm);
+     *
+     * @example
+     * const perm = array.argsort([key1, key2], [1, -1]);
+     * return dataRange.take(perm);
+     *
+     * @param keyRanges Single key range or array of key ranges.
+     * @param orders `1` for ascending (default), `-1` for descending, per key.
+     * @param axis Sort by rows (default) or columns.
+     */
+    argsort(keyRanges: IRange | IRange[], orders?: number | number[], axis?: IRange.Axis): number[];
+    /**
+     * Returns the indices of the distinct rows (or columns) in this range, keeping the FIRST
+     * occurrence of each. Analogous to `np.unique(arr, axis=0, return_index=True)`, but returning
+     * only the kept indices (numpy's sorted, unique-value form isn't what `UNIQUE()` wants).
+     *
+     * @param axis Dedupe rows (default) or columns.
+     * @param exactlyOnce If true, keep only rows/columns that occur EXACTLY once — drops every
+     *   row that has a duplicate, rather than keeping one copy of it. Default false.
+     *
+     * @example
+     * const kept = range.uniqueIndices();
+     * return range.take(kept); // the SORTBY-style pattern argsort's own docs use
+     */
+    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.
+     *
+     * **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.
+     *
+     * @param other The other range or scalar to broadcast with.
+     * @param callbackFn The function to apply to corresponding elements.
+     * @param options {@link IRange.BroadcastOptions}
+     *
+     * @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)
+     */
+    broadcast<TS extends Scalar = T>(other: IRange | TS, callbackFn: (a: TS, b: TS, coords: IRange.CellCoords, range: IRange<T>) => TS, options?: IRange.BroadcastOptions): this;
+    /**
+     * Selects values from `from` by dispatching each element of `condition` to a 0-based index.
+     *
+     * For each cell, `selectFn` receives the corresponding value from `condition` and returns a 0-based
+     * index into `from`. If the index is out of bounds, the original value from `this` is kept.
+     *
+     * **Broadcasting Rules:**
+     * - Output shape is the max of `this`, `condition`, and all `from` ranges.
+     * - All inputs are clamped to their bounds (NumPy-style broadcasting).
+     * - Out-of-bounds index from `selectFn` falls back to `this` at that position.
+     *
+     * @param from The candidate ranges or scalars to select from (0-based).
+     * @param selectFn Maps each condition value to a 0-based index into `from`.
+     *   Return `-1` (or any out-of-bounds value) to keep the original value from `this`.
+     * @param options {@link IRange.ValuesOptions}
+     *
+     * @returns A new range with selected values overlaid onto `this`.
+     *
+     * @see {@link mask} for the boolean shorthand (single condition, single value range).
+     */
+    choose<TS extends Scalar = T>(from: (IRange<TS> | TS)[], selectFn: (value: TS, coords: IRange.CellCoords, range: IRange<T>) => MaybeError<number>, options?: IRange.ValuesOptions): this;
+    /**
+     * Similar to {@link empty}, but returns an range with the same size but `null` values.
+     */
+    clear(): this;
+    /**
+     * Returns a new range identical to the current one.
+     */
+    clone(): this;
+    /**
+     * Applies a transformation function to this `IRange`, returning the result.
+     *
+     * Equivalent to `fn(this)` — useful for applying named or reusable transforms
+     * inline without breaking a fluent method chain.
+     *
+     * @param fn A pure function that transforms this `IRange`.
+     *
+     * @example
+     * const normalize = (r: IRange) => r.replace([[1,2,3]]).repeat(3,1);
+     *
+     * range.compute(normalize).mask(condition);
+     */
+    compute(fn: (range: IRange) => IRange): this;
+    /**
+     * Concatenates another range along the specified axis, returning a new range.
+     *
+     * - {@link IRange.Axis.Row} (default) — vertical stack:
+     *   appends `other` below `this`. Both ranges must have the same column size, or the
+     *   narrower is padded to the wider with `padWith`.
+     * - {@link IRange.Axis.Column} — horizontal stack:
+     *   appends `other` to the right of `this`. Both ranges must have the same row size,
+     *   or the shorter is padded to the taller with `padWith`.
+     *
+     * @param other The range to append.
+     * @param axis The axis to concatenate along. Default is {@link IRange.Axis.Row}.
+     * @param padWith Value used to pad the narrower/shorter range. Default is `#N/A`.
+     *
+     * @remarks
+     * Analogous to `np.vstack` / `np.hstack` in numpy and `torch.cat` in PyTorch.
+     *
+     * @example
+     * // Vertical stack
+     * a.concat(b)
+     *
+     * @example
+     * // Horizontal stack
+     * a.concat(b, IRange.Axis.Column)
+     *
+     * @example
+     * // Pad with 0 instead of #N/A
+     * a.concat(b, IRange.Axis.Row, 0)
+     */
+    concat(other: IRange, axis?: IRange.Axis, padWith?: Scalar): this;
+    /**
+     * Returns a range of 0x0.
+     */
+    empty(): this;
+    /**
+     * Returns an iterator that allows you to iterate over the individual entries within the range,
+     * yielding pairs of `IRange.CellCoords` and `Scalar`.
+     *
+     * @param options {@link IRange.IteratorOptions}
+     * @returns An iterator that yields a IRange.Entry for each value within the range.
+     *
+     * @remarks
+     * Skips empty values by default.
+     *
+  ```typescript entries
+    const iterEntries:IterableIterator<IRange.Entry> = array.entries({
+      axis: IRange.Axis.Row, // Default but Column and 'fastest' are also available
+      includeEmpty: false // Default but true is also available but should be avoided if sparse.
+    });
+  
+    let iter: IteratorResult<IRange.Entry> = iterEntries.next();
+    while (!iter.done) {
+      const entry = iter.value;
+      const value = entry.value;
+      const coords: Readonly<IRange.CellCoords> = entry.coords;
+      iter = iterEntries.next();
+      // ...interesting logic here. Perhaps a sparseBuilder.
+    }
+  ```
+     */
+    entries<TS extends Scalar = T>(options?: IRange.IteratorOptions): IterableIterator<IRange.Entry<TS>>;
+    /**
+     * Iterates the range's error members — every stored `FormulaError` — in row-major order
+     * by default. Row-major is the identity order: `errors().next()` yields the error that
+     * propagates under the engine's reject policy (`#N/A` stays `#N/A`).
+     *
+     * @param options Narrowed iterator options — only `axis`, `bounds`, and `reverse`.
+     * The narrowing is deliberate: `type`/`onError`/`coerce` are meaningless-to-contradictory
+     * on an error iterator. Like {@link hasError}, the scan reads RAW stored members,
+     * ignoring the range's read type and coercion policy.
+     *
+     * @see {@link hasError} for existence-only checks.
+     */
+    errors(options?: Pick<IRange.IteratorOptions, 'axis' | 'bounds' | 'reverse'>): IterableIterator<IRange.Entry<FormulaError.Known>>;
+    /**
+     * Tests whether all elements in the range pass the test implemented by the provided function.
+     *
+     * @param callbackFn The function to test each element.
+     * @param options {@link IRange.IteratorOptions}
+     * @returns `true` if all elements pass the test, otherwise `false`.
+     */
+    every<TS extends Scalar = T>(callbackFn: (value: TS, coords: IRange.CellCoords, range: IRange<T>) => boolean, options?: IRange.IteratorOptions): boolean;
+    /**
+     * Fill the entire range with a single value.
+     *
+     * @param value The value to fill.
+     * @param coords If provided will fill from the coordinates to this area.
+     *
+     * @remarks
+     * If the coords are outside the range then it will fill to the edge.
+     * Does not resize
+     */
+    fill(value: Scalar, coords?: Partial<IRange.Coords>): this;
+    /**
+     * Fill all empty values in the range with a single value.
+     *
+     * @param value The value to fill
+     * @param coords If provided will fill from the coordinates to this area.
+     */
+    fillEmpty(value: Scalar, coords?: Partial<IRange.Coords>): this;
+    /**
+     * Creates a new range with elements that pass the test implemented by the provided function.
+     *
+     * @param callbackFn The function to test each element.
+     * @param options {@link IRange.IteratorOptions}
+     * @returns A new range containing only the elements that pass the test.
+     *
+     * @remarks
+     * If the callback returns an error this will propagate the error as the value with the error.
+     */
+    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.
+     *
+     * @param options {@link IRange.IteratorOptions}
+     */
+    flatten<TS extends Scalar = T>(options?: IRange.IteratorOptions): TS[];
+    /**
+     * Iterates over the cells within the range, applying the provided callback function to each cell.
+     *
+     * This method is a more scalable alternative to `getValues` or `getCells` for large or sparse ranges,
+     * as it:
+     * 1. Skips empty values by default.
+     * 2. Avoids creating large arrays.
+     * 3. Allows for early termination.
+     *
+     * @param callbackFn A function that will be called for each non-empty cell in the range. The callback receives:
+     *   - `value`: The `Scalar` at the current cell.
+     *   - `coords`: A `IRange.CellCoords`.
+     *   - The callback can return `{ break: T }` to stop the iteration early.
+     * @param options {@link IRange.IteratorOptions}
+     * @template T The Scalar type.
+     * @template B The callback return type.
+     * @returns The value returned by the callback function if it explicitly returned to stop the iteration early; otherwise, `void`.
+     */
+    forEach<TS extends Scalar = T, B = any>(callbackFn: (value: TS, coords: IRange.CellCoords, range: IRange<T>) => {
+        break: B;
+    } | void, options?: IRange.IteratorOptions): B | void;
+    /**
+     * Returns the shape of the range in rows and columns.
+     */
+    getShape(): {
+        rows: number;
+        columns: number;
+    };
+    /**
+     * Returns the statistics for the range.
+     */
+    getStats(options?: IRange.IteratorOptions): IRangeStats;
+    /**
+     * Returns `true` if any stored member of the range is a `FormulaError`.
+     *
+     * @remarks
+     * Reads RAW stored members only — the range's read type and coercion policy are ignored.
+     * A `toType(Number)` range with a text member does NOT "have an error"; a `#VALUE!`
+     * synthesized by `errorOnInvalidCoercion` doesn't count.
+     *
+     * The result is EXACT, never conservative: `false` guarantees there are no error members.
+     * (Internal fast paths may be conservative; the public result may not be.)
+     *
+     * Equivalent by definition to
+     * `getStats().getTypedCounts([ScalarType.Error])[ScalarType.Error] > 0` — the two
+     * definitions of "error member" must never drift.
+     *
+     * Deliberately takes no options: partial regions compose —
+     * `range.slice(coords).hasError()` (slice is a zero-copy view).
+     *
+     * @see {@link errors} to iterate the error members themselves.
+     */
+    hasError(): boolean;
+    /**
+     * Indicates if the range has a type. Returns `undefined` when no type was set —
+     * consumers compare against an (optionally undefined) requested type, so `null`
+     * must NOT be substituted here.
+     */
+    getType(): ScalarType | undefined;
+    /**
+     * Returns the values as a materialized 2D array.
+     *
+     * @param options {@link IRange.GetValuesOptions}
+     *
+     * @remarks
+     * This is useful for libraries or functions that require a
+     * a materialized 2D array but is expensive for large ranges.
+     */
+    getValues<TS extends Scalar = T>(options?: IRange.GetValuesOptions): TS[][];
+    /**
+     * Returns a scalar value at a specific row and column index.
+     *
+     * @param rowIndex The row index of the value to retrieve.
+     * @param colIndex The column index of the value to retrieve.
+     * @param options {@link IRange.ValueOptions}
+     */
+    getValueAt<TS extends Scalar = T>(rowIndex: number, colIndex: number, options?: IRange.ValueOptions): TS;
+    /**
+     * Returns the number of columns of the range.
+     */
+    getColumnCount(): number;
+    /**
+     * Returns the number of rows of the range.
+     */
+    getRowCount(): number;
+    /**
+     * Applies a transformation function to each value, returning a new `IRange`.
+     *
+     * @param callbackFn A function applied to each non-empty cell
+     * @param options {@link IRange.IteratorOptions}
+     *
+     * @remarks
+     * The result carries NO read type, even when the source had one — the values are the callback's
+     * 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;
+    /**
+     * Returns a new range where each cell is replaced with the value from `ifTrues`
+     * where the corresponding `conditions` value is strictly `true`.
+     *
+     * @param conditions A range of values determining which cells are replaced.
+     * @param ifTrues Values to use where `conditions` is `true` (specifically not truthy).
+     *
+     * @remarks
+     * The mask rules are:
+     * 1. If the condition is `true` then the value from `ifTrues` is used.
+     * 2. If the condition is an error then that error is used.
+     * 3. If the condition is outside the bounds of `ifTrues` then `options.misalignValue` is used (default `#N/A`).
+     * 4. Else the original value is kept.
+     *
+     * Similar to pandas `DataFrame.mask(cond, other)`.
+     *
+     * @example
+     * // Formula equivalent: =IF(A1:A10>0, B1:B10, 0)
+     * original.mask(conditions, ifTrues)
+     *
+     * @see {@link broadcast} for element-wise transformation with a callback
+     */
+    mask<TS extends Scalar = T>(conditions: IRange | TS, ifTrues: IRange | TS, options?: IRange.MaskOptions): this;
+    /**
+     * Iterates this range and any number of other ranges in lockstep, yielding the corresponding
+     * values at each position — `values[0]` is this range's member, `values[i+1]` is `others[i]`'s.
+     *
+     * Positions are aligned by OFFSET from each range's start; there is no broadcasting or tiling —
+     * dimension rules stay with the caller. Iteration is sparse: a position empty in EVERY range is
+     * never visited, and a range with no member at a visited position contributes `null`. Each range
+     * reads through its own declared type, so a filtered member (e.g. text under a `number` read)
+     * surfaces as `null` exactly like an empty cell.
+     *
+     * A `null` entry in `others` contributes the 1-based POSITION ordinal instead — the implied
+     * `{1,2,...,n}` sequence. The ordinal is positional within this range's shape (empties advance it),
+     * so a sparse member keeps the ordinal its cell occupies.
+     *
+     * @param others The parallel ranges; `null` entries yield the 1-based position ordinal.
+     * @param options {@link IRange.IteratorOptions} Applied to this range's read; `axis` orders the
+     * iteration for all sides.
+     * @returns Pairs of `[values, coords]` with `coords` relative to this range.
+     */
+    alignValues<TS extends Scalar = T>(others: (IRange | null)[], options?: IRange.IteratorOptions): IterableIterator<[values: (TS | null)[], coords: IRange.CellCoords]>;
+    /**
+     * Reduces this range and any number of other ranges in lockstep — the fused, streaming form of
+     * "align, apply an elementwise kernel, fold" (numpy's `f(a, b).sum()`, with no intermediate
+     * range). Iteration and alignment follow {@link alignValues}: positions align by offset,
+     * a position empty on every side is never visited, an absent/filtered member arrives as
+     * `null`, and a `null` in `others` contributes the 1-based position ordinal.
+     *
+     * Value policy (what to skip, how to accumulate) belongs to the callback — this is the same
+     * contract as {@link reduce}, over aligned members.
+     *
+     * @template U The type of the accumulator.
+     * @param others The parallel range(s); `null` entries yield the 1-based position ordinal.
+     * @param callbackFn The function to execute on each aligned position — `values[0]` is this
+     * range's member, `values[i+1]` is `others[i]`'s.
+     * @param initialValue The initial value of the accumulator.
+     * @param options {@link IRange.ReduceOptions} Applied to this range's read; `axis` orders the
+     * iteration for all sides. Supply `emptyFold` when the answer depends on the positions that are
+     * empty on every side — they are never visited, so a fold that needs them must state their
+     * contribution in closed form.
+     * @returns The reduced value.
+     */
+    alignReduce<TS extends Scalar = T, U = TS>(others: IRange | null | (IRange | null)[], callbackFn: (accumulator: U, values: (TS | null)[], coords: IRange.CellCoords, range: IRange<T>) => U, initialValue: U, options?: IRange.ReduceOptions<U>): U;
+    /**
+     * Applies a function against an accumulator and each element of the range (from left to right) to reduce it to a single value.
+     *
+     * @template U The type of the accumulator.
+     * @param callbackFn The function to execute on each element.
+     * @param initialValue The initial value of the accumulator.
+     * @param options {@link IRange.IteratorOptions}
+     * @returns The reduced value.
+     *
+     * @remarks
+     * Iteration is sparse — empty cells are not visited. A fold whose answer DEPENDS on the empty
+     * cells wants {@link alignReduce}'s `emptyFold`, which states their contribution in closed form;
+     * pass no `others` for the single-range case.
+     */
+    reduce<TS extends Scalar = T, U = TS>(callbackFn: (accumulator: U, value: TS, coords: IRange.CellCoords, range: IRange<T>) => U, initialValue: U, options?: IRange.IteratorOptions): U;
+    /**
+     * Repeat the values in the range to a new width and height by repeating individual values.
+     *
+     * @param rows Number of times to repeat each value vertically.
+     * @param columns Number of times to repeat each value horizontally.
+     *
+     * @remarks
+     * **Note**: Arguments follow matrix convention `(rows, columns)`, not geometric order `(columns, rows)`.
+     *
+     * `[1, 2].repeat(1, 3)` → `[1, 1, 1, 2, 2, 2]`  *(expand horizontally)*
+     * `[1, 2].repeat(2, 1)` → `[[1, 2], [1, 2]]`     *(expand vertically)*
+     *
+     * To repeat the entire range as a block, see {@link tile}.
+     */
+    repeat(rows: number, columns: number): this;
+    /**
+     * Reflows the range's members into a new shape by flattened row-major ordinal — numpy's
+     * `reshape`: the member at flattened position `i` lands at row `⌊i / columns⌋`, column
+     * `i % columns`. Empty positions keep their ordinal (they reflow as gaps), so sparse ranges
+     * stay sparse.
+  
+     * Contrast {@link resize}, which trims/pads in place WITHOUT reflowing, and {@link repeat} /
+     * {@link tile}, which duplicate values.
+     *
+     * @param rows The new number of rows.
+     * @param columns The new number of columns.
+     */
+    reshape(rows: number, columns: number): this;
+    /**
+     * Returns a new range with values from another range overlaid at the given offset.
+     * Where they overlap, other wins. If other extends beyond this, the range expands.
+     *
+     * @param other The other range or a 2D array.
+     * @param offset The starting coordinates for the replacement. Default: { rowIndex: 0, colIndex: 0 }
+     */
+    replace<TS extends Scalar = T>(other: IRange | TS[][], offset?: IRange.CellCoords): this;
+    /**
+     * Returns a new range either trimmed or expanded to the new rows and columns.
+     *
+     * @param rows The new number of rows of the range.
+     * @param cols The new number of columns of the range.
+     * @param fillValue If provided then when expanding the new cells will be filled with this value. DefaultValue `null`
+     */
+    resize(rows: number, cols: number, fillValue?: Scalar): this;
+    /**
+     * Returns a sliced subrange of the current range.
+     *
+     * @param coords A partial range definition ({ rowStart, rowEnd, colStart, colEnd }).
+     * @returns A new `IRange` representing the sliced section.
+     *
+     * @remarks
+     * If any coordinate is omitted, it defaults to the full extent of the range.
+     */
+    slice(coords: Partial<IRange.Coords>): this;
+    /**
+     * Tests whether at least one element in the range passes the test implemented by the provided function.
+     *
+     * @param callbackFn The function to test each element.
+     * @param options {@link IRange.IteratorOptions}
+     * @returns `true` if at least one element passes the test, otherwise `false`.
+     */
+    some<TS extends Scalar = T>(callbackFn: (value: TS, coords: IRange.CellCoords, range: IRange<T>) => boolean, options?: IRange.IteratorOptions): boolean;
+    /**
+     * Returns a sorted copy of the range along the given axis.
+     * Equivalent to `this.take(this.argsort(order, axis), axis)`.
+     *
+     * @param order - `1` for ascending (default), `-1` for descending.
+     * @param axis - Sort rows (`Row`, default) or columns (`Column`).
+     */
+    sort(order?: number, axis?: IRange.Axis): this;
+    /**
+     * Similar to {@link choose}, but matches by value equality rather than by index.
+     *
+     * For each cell, searches `match` for the first element equal to the expression value and returns
+     * the corresponding element from `from`. If no match is found, `defaultValue` is used (or the
+     * original value from `this` if no default is provided).
+     *
+     * @param match Values to match against the expression range.
+     * @param from Values to return for each corresponding match.
+     * @param defaultValue Fallback value when no match is found.
+     * @param selectFn Optional custom equality function. Defaults to strict equality (`===`).
+     * @param options {@link IRange.ValuesOptions}
+     *
+     * @see {@link choose} for index-based dispatch.
+     */
+    select<TS extends Scalar = T>(match: IRange<TS> | TS | (IRange<TS> | TS)[], from: (IRange<TS> | TS)[], defaultValue?: IRange<TS> | TS, selectFn?: (value: TS, coords: IRange.CellCoords, matchValue: TS, matchCoords: IRange.CellCoords, range: IRange<T>) => MaybeError<boolean>, options?: IRange.ValuesOptions): this;
+    /**
+     * Creates a `SparseBuilder` for efficiently updating sparsely populated values in a streaming low memory way.
+     *
+     * @param options {@link IRange.SparseBuilderOptions}
+     *
+     * @remarks
+     * - **Ordering:** By default updates must be added in either row-major or column-major order, as specified
+     * by the `axis` parameter, with major/minor coordinates increasing monotonically. Unless
+     * `allowUnorderedWrites` is set to `true` out of order updates will result in an error.
+  
+     * - **Performance:**  Setting `axis` to `IRange.Axis.Column` is generally faster as it aligns with the internal data representation.
+     * - **Performance:**  Setting `allowUnorderedWrites` adds a nominal performance overhead for all updates and will do a full apply when an
+     *      out of order update is detected.
+     *   The default `IRange.Axis.Row` is provided for compatibility with common spreadsheet APIs.
+     *
+     * @example
+  ```typescript sparseBuilder
+    const updatedRange = range.sparseBuilder()
+      .pushAt(0, 0, 'A1')
+      .pushAt(0, 1, 'B1')
+      .build();
+  ```
+     */
+    sparseBuilder<TS extends Scalar = T>(options?: IRange.TraversalAxis | IRange.SparseBuilderOptions): IRange.SparseBuilder<TS>;
+    /**
+     * Returns a new range by selecting values at the given indices along the specified axis.
+     * The output size along the selected axis equals `indices.length` — no resizing is applied.
+     *
+     * Indices refer to positions within this range (0-based, relative to origin).
+     * The same index may appear multiple times to repeat rows or columns.
+     *
+     * @param indices The positions to select, in the desired output order.
+     * @param axis The axis to select along. Default is {@link IRange.Axis.Row}
+     *   (select rows). Pass {@link IRange.Axis.Column} to select columns.
+     *
+     * @remarks
+     * Analogous to `np.take` in numpy and `torch.index_select` in PyTorch.
+     *
+     * @example
+     * // Reverse rows
+     * range.take([2, 1, 0])
+     *
+     * @example
+     * // Select columns 0 and 2, dropping column 1
+     * range.take([0, 2], IRange.Axis.Column)
+     *
+     * @example
+     * // Repeat a row
+     * range.take([0, 0, 1, 2])
+     */
+    take(indices: readonly number[], axis?: IRange.Axis): this;
+    /**
+     * Tile the range to a new width and height by repeating blocks of values.
+     *
+     * @param rows Number of times to tile the range vertically.
+     * @param columns Number of times to tile the range horizontally.
+     *
+     * @remarks
+     * **Note**: Arguments follow matrix convention `(rows, columns)`, not geometric order `(columns, rows)`.
+     *
+     * `[1, 2, 3].tile(1, 3)` → `[[1, 2, 3, 1, 2, 3, 1, 2, 3]]`       *(tile horizontally 3×)*
+     * `[1, 2, 3].tile(3, 1)` → `[[1, 2, 3], [1, 2, 3], [1, 2, 3]]`  *(tile vertically 3×)*
+     *
+     * To repeat individual values instead of blocks, see {@link repeat}.
+     */
+    tile(rows: number, columns: number): this;
+    /**
+     * Returns the scalar value of the range if it is a 1×1 range, otherwise throws an error.
+     */
+    toScalar(): Scalar;
+    /**
+     * Change the type of default range coercion for the values in the range.
+     *
+     * @param type The new scalar type or value options.
+     */
+    toType(type: ScalarType | IRange.ValueOptions): this;
+    /**
+     * Returns the range transposed.
+     */
+    transpose(): this;
+    /**
+     * Iterate values.
+     *
+     * @param options {@link IRange.IteratorOptions}
+     *
+     * @remarks
+     * Skips empty values by default.
+     */
+    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.
+     *
+     * @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.
+     */
+    zip(others: (IRange | Scalar)[], callbackFn: (values: Scalar[], coords: IRange.CellCoords, range: IRange<T>) => Scalar, options?: IRange.IteratorOptions): 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.
+     */
+    isEmpty(): boolean;
+    /**
+     * Returns the size of the range this is the rows * columns.
+     */
+    get size(): number;
+    /**
+     * Returns an iterator that allows you to iterate over the individual values within the range.
+     *
+     * @remarks
+     * For more advanced iteration, use {@link IRange.entries} or {@link IRange.forEach}.
+     */
+    [Symbol.iterator](): IterableIterator<Scalar>;
+    /**
+     * Use for introspection.
+     */
+    get isIRange(): true;
+}
+/**
+ * {@inheritDoc IRange}
+ *
+ * @see
+ * ### **Interface**
+ *
+ * {@link IRange}
+ */
+export declare namespace IRange {
+    /**
+     * Options for controlling iteration behavior.
+     */
+    interface IteratorOptions extends IRange.ValueOptions {
+        /**
+         * The direction of the iteration.
+         *
+         * @defaultValue `IRange.Axis.Row`
+         *
+         * @remarks
+         * If `axis` is set to `'fastest'`, the implementation will automatically choose the fastest axis
+         * for iteration based on the internal data layout of the range.
+         * This can provide performance benefits without requiring the caller to specify the axis,
+         * especially when the optimal axis is not known in advance.
+         */
+        axis?: IRange.TraversalAxis;
+        /**
+         * The bounds of the iteration.
+         *
+         * @defaultValue `The entire range`
+         */
+        bounds?: Partial<IRange.Coords>;
+        /**
+         * Iterate in reverse order.
+         *
+         * @defaultValue `false`
+         */
+        reverse?: boolean;
+        /**
+         * If true will visit empty cells.
+         * This is a potentially huge performance improvement if set to false.
+         *
+         * @defaultValue `false`
+         *
+         * @remarks
+         * If includeEmpty is `true` this will always return rectangular results.
+         * If bounds are provided it will provide empty spaces before and after.
+         * If passing a large bound care must be taken.
+         */
+        includeEmpty?: boolean;
+        /**
+         * Useful for callback functions that want a this.
+         */
+        thisArg?: any;
+    }
+    /**
+     * Options for a fold — {@link IRange.alignReduce}.
+     */
+    interface ReduceOptions<U = any> extends IRange.IteratorOptions {
+        /**
+         * Folds the positions the iteration never visited — the cells that are empty on EVERY side —
+         * in a single call, given how many there are.
+         *
+         * @param accumulator The accumulator after every visited position has been folded.
+         * @param count How many positions of this range's shape went unvisited. Never `0`: the fold
+         * is skipped entirely when the iteration was dense.
+         *
+         * @remarks
+         * A sparse fold visits stored members only, which is the whole point of it and is why
+         * `SUM(A:A)` is not a million calls. But a reducer whose answer DEPENDS on the blanks —
+         * `COUNTIF(A:A,"<>10")` is 1,048,576 — needs their contribution, and iterating them to get
+         * it gives the cost back. The contribution is the same term repeated, so it is stated in
+         * closed form here and applied once.
+         *
+         * This is the caller's to supply because only the caller knows the fold: `COUNTIF` adds the
+         * count, `SUMIF` and `MAXIFS` are unchanged by a blank and pass nothing at all. It is the
+         * open-ufunc analogue of numpy's `initial=` — numpy hard-codes the identity per reduction
+         * because its set is closed, and this cannot.
+         *
+         * Omit it and the unvisited positions contribute nothing, which is the behavior every fold
+         * had before this option existed.
+         */
+        emptyFold?: (accumulator: U, count: number) => U;
+    }
+    /**
+     * Union type for coercion parameters.
+     */
+    type CoerceParams = ScalarType[] | ((fromValue: Scalar, fromType: ScalarType, defaultCoerce: (value: Scalar, type: ScalarType) => Scalar, range: IRange) => Scalar);
+    /**
+     * Passed to various methods to control coercion behavior when getting or iterating values.
+     */
+    interface ValueOptions {
+        /**
+         * Specifies the target type for coercion and filtering when getting or
+         * iterating values.
+         *
+         * @defaultValue The scalar type of the `IRange` itself (`getType()`)
+         *
+         * @remarks
+         * - Values matching the type pass through unchanged.
+         * - Values coercible to the type are coerced.
+         * - If not set, the range's own scalar type (`getType()`) is used.
+         * - If the range has no scalar type, or set to `null` explicitly,
+         *   no coercion or filtering is performed.
+         */
+        type?: ScalarType | null;
+        /**
+         * Overrides default coercion behavior per type.
+         * When a value cannot be coerced, {@link onError} determines the fallback.
+         */
+        coerce?: IRange.CoerceParams;
+        /**
+         * If `true`, coercion failure produces `#VALUE!` rather than silently skipping the value.
+         *
+         * @defaultValue `false`
+         */
+        errorOnInvalidCoercion?: boolean;
+        /**
+         * What to do when the visited value is a `FormulaError`.
+         *
+         * @defaultValue `throw`
+         *
+         * @remarks
+         * 'throw' = throw error.
+         * 'ignore' = silently skip the value.
+         * 'value' = return a specific error value (default `#VALUE!`).
+         * 'function' = custom handler; use this to return a specific error value.
+         */
+        onError?: 'throw' | 'ignore' | 'value' | ((error: FormulaError.Known) => void);
+    }
+    interface GetValuesOptions extends IRange.ValueOptions {
+        /**
+         * The maximum number of rows of the array.
+         */
+        maxRows?: number;
+        /**
+         * The maximum number of columns of the array.
+         */
+        maxCols?: number;
+        /**
+         * If true will include trailing empties.
+         */
+        trailingEmpties?: boolean;
+        /**
+         * Allow for this to be set. DefaultValue `IRange.Axis.Row`
+         */
+        axis?: IRange.Axis;
+        /**
+         * If provided then before return the callback will be visited for each cell.
+         */
+        onValue?: (value: Scalar, row: number, column: number, range: IRange) => Scalar;
+    }
+    /**
+     * Options used during range over range operators.
+     */
+    interface ValuesOptions extends IRange.ValueOptions {
+        /**
+         * Controls how misaligned ranges are handled during broadcasting.
+         *
+         * - By default, `broadcast()` follows strict alignment rules like NumPy and will
+         *   throw an error if the input ranges cannot be broadcasted together.
+         * - When `misalignValue` is provided, `broadcast()` will instead mimic Excel behavior:
+         *   - It finds the **largest valid intersection** of the ranges.
+         *   - 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.
+         *
+         * @example
+         * // Throws an error if A and B are not naturally broadcast-compatible
+         * const result = A.broadcast(B, (a, b) => a + b);
+         *
+         * @example
+         * // Expands to union size and fills gaps with "#N/A" instead of erroring
+         * const result = A.broadcast(B, (a, b) => a + b, { misalignValue: "#N/A" });
+         */
+        misalignValue?: Scalar;
+    }
+    /**
+     * Options used during broadcasting.
+     */
+    interface BroadcastOptions extends IRange.ValuesOptions {
+        /**
+         * Coerces values from `other` to the specified type before applying the callback.
+         * Overrides the type inference that would otherwise be derived from `other`.
+         */
+        otherType?: ScalarType;
+    }
+    /**
+     * Options used during masking.
+     */
+    interface MaskOptions extends IRange.ValuesOptions {
+        /**
+         * Determines whether a condition value is considered true.
+         *
+         * @defaultValue `(cond) => cond === true`
+         */
+        isTrue?: (cond: Scalar, cell: IRange.CellCoords) => boolean;
+        /**
+         * Value substituted for empty cells during masking.
+         *
+         * @defaultValue `null`
+         */
+        emptyValue?: Scalar;
+    }
+    /**
+     * Entry for a Range iterator or visiting.
+     */
+    interface Entry<T extends Scalar = Scalar> {
+        /**
+         * The value of the cell for this entry.
+         */
+        value: T;
+        /**
+         * Coordinates of the cell for this entry.
+         *
+         * @remarks
+         * This should not be used as keys. For performance reasons the same object may be reused across iterations and should be treated as immutable.
+         */
+        coords: Readonly<IRange.CellCoords>;
+    }
+    /**
+     * The direction to traverse a range, either by row or by column,
+     * or let the implementation decide the fastest way.
+     */
+    type TraversalAxis = IRange.Axis | 'fastest';
+    interface TraversalAxisOptions {
+        /**
+         * The direction of the write.
+         *
+         * @defaultValue `IRange.Axis.Row`
+         */
+        axis?: TraversalAxis;
+    }
+    /**
+     * Options for the {@link IRange.sparseBuilder}.
+     *
+     * @remarks
+     * See {@link IRange.sparseBuilder} for details and ordering/performance tradeoffs.
+     */
+    interface SparseBuilderOptions extends TraversalAxisOptions {
+    }
+    /**
+     * A Builder for setting values in a streaming sparse grid.
+     *
+     * @template T The type of values stored within the tuples.
+     *
+     * @remarks
+     * Coordinates must increase monotonically in the current axis — row then
+     * column in row-major mode, column then row in column-major mode.
+     */
+    interface SparseBuilder<T extends Scalar = Scalar> {
+        /**
+         * Adds a single value associated with a specific major and minor index.
+         *
+         * @param row The row index.
+         * @param col The column index.
+         * @param value The value to be added.
+         * @throws `Error` If the point is out of order compared to previously added points
+         * (within the same row).
+         *
+         * @remarks
+         * If the value is an Array, it will be treated as a discrete value. If you want to set
+         * multiple values along the minor axis, then use {@link pushMultipleAt}.
+         */
+        pushAt(row: number, col: number, value: T): this;
+        /**
+         * Adds multiple values associated with a specific row and column index.
+         *
+         * @param row The row index.
+         * @param col The column index.
+         * @param value The values to add. Accepts an {@link IRange} or a native array.
+         * 2D ranges are flattened in row-major order.
+         * @throws `Error` If the point is out of order compared to previously added points
+         * (within the same row).
+         */
+        pushMultipleAt(row: number, col: number, value: IRange | T[]): this;
+        /**
+         * Apply the updates.
+         */
+        build(): IRange<T>;
+    }
+    /**
+     * Specifies a single direction for the range.
+     */
+    const Axis: {
+        readonly Column: "column";
+        readonly Row: "row";
+    };
+    type Axis = typeof Axis[keyof typeof Axis];
+    /**
+     * Allows for either direction or both. (But not none).
+     */
+    const AxisSelection: {
+        readonly Both: "both";
+        readonly Column: "column";
+        readonly Row: "row";
+    };
+    type AxisSelection = typeof AxisSelection[keyof typeof AxisSelection];
+    /**
+     * Indicates a direction for a range along an axis.
+     *
+     * @remarks
+     * Used during fill, shift, etc.
+     */
+    const Direction: {
+        readonly Up: "up";
+        readonly Down: "down";
+        readonly Left: "left";
+        readonly Right: "right";
+    };
+    type Direction = typeof Direction[keyof typeof Direction];
+    /**
+     * The coordinates of an Range in a 2D space.
+     * The rowStart and colStart must be less than or equal to rowEnd and colEnd respectively.
+     */
+    interface Coords {
+        /**
+         * Left column
+         */
+        colStart: number;
+        /**
+         * Top row
+         */
+        rowStart: number;
+        /**
+         * Right column
+         */
+        colEnd: number;
+        /**
+         * Bottom row
+         */
+        rowEnd: number;
+        /**
+         * An optional identifier for the 2D space these coordinates are relative to.
+         */
+        scope?: string | null;
+    }
+    /**
+     * The coordinates of a single cell in a 2D space.
+     */
+    interface CellCoords {
+        /**
+         * The column index of the cell.
+         */
+        colIndex: number;
+        /**
+         * The row index of the cell.
+         */
+        rowIndex: number;
+        /**
+         * An optional identifier for the 2D space these coordinates are relative to.
+         */
+        scope?: string | null;
+    }
+    /**
+     * Adds `fixed flags` to `IRange.Coords`.
+     */
+    interface FixableCoords extends IRange.Coords {
+        /**
+         * If `true` then the colStart is fixed.
+         *
+         * @defaultValue false
+         */
+        $colStart?: boolean;
+        /**
+         * If `true` then the rowStart is fixed.
+         *
+         * @defaultValue false
+         */
+        $rowStart?: boolean;
+        /**
+         * If `true` then the colEnd is fixed.
+         *
+         * @defaultValue false
+         */
+        $colEnd?: boolean;
+        /**
+         * If `true` then the rowEnd is fixed.
+         *
+         * @defaultValue false
+         */
+        $rowEnd?: boolean;
+    }
+    /**
+     * Adds fixable flag to `IRange.CellCoords`.
+     */
+    interface FixableCellCoords extends CellCoords {
+        /**
+         * If `true`, the column is fixed.
+         */
+        $colIndex?: boolean;
+        /**
+         * If `true`, the row is fixed.
+         */
+        $rowIndex?: boolean;
+    }
+    /**
+     * A address can be Either a `Partial<IRange.FixableCoords>`, a `FormulaError.Known` or a named range `string`.
+     */
+    type Address = Partial<IRange.FixableCoords> | FormulaError.Ref | FormulaError.Name | string;
+    /**
+     * Serialize coords.
+     *
+     * @remarks
+     * A single coords, several coords, or an address string. Items that anchor to several ranges
+     * (data validations, conditional formats, protected ranges) serialize as a comma-separated
+     * string (`'A1:B2,D5:D9'`); the coords-array form is accepted on load but never emitted.
+     */
+    type JSONCoords = IRange.Coords | readonly IRange.Coords[] | string;
+    /**
+     * A serialized address-value pair as an object.
+     */
+    interface JSONReferenceEntry<J = any> {
+        /**
+         * Range Address
+         */
+        r: JSONCoords;
+        /**
+         * Value
+         */
+        v: J;
+    }
+    /**
+     * A serialized address-value pair as an array tuple.
+     */
+    type JSONReferenceTuple<J = any> = [range: JSONCoords, value: J];
+    /**
+     * A serialized address-value pair — either object or tuple form.
+     *
+     * @see {@link JSONReferenceEntry} {@link JSONReferenceTuple}
+     */
+    type JSONReference<J = any> = JSONReferenceEntry<J> | JSONReferenceTuple<J>;
+}
+//# sourceMappingURL=IRange.d.ts.map