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

package/types/src/primitives/stats/FrequencyStats.d.ts

@@ -7,6 +7,13 @@ import { ISparseGrid } from '../../collections';
 export interface FrequencyGroup {
     readonly value: Scalar;
     count: number;
+    /** Bounding box of the occurrences, in grid coordinates; absent when not tracked (merged, blank). */
+    extent?: {
+        rowStart: number;
+        colStart: number;
+        rowEnd: number;
+        colEnd: number;
+    };
 }
 /**
  * Implements {@link IRangeStats.IFrequency}.
@@ -53,6 +60,8 @@ export declare class FrequencyStats implements IRangeStats.IFrequency {
     getTotalCount(): number;
     /** @inheritdoc IRangeStats.IFrequency.isTruncated */
     isTruncated(): boolean;
+    /** @inheritdoc IRangeStats.IFrequency.getExtent */
+    getExtent(value: Scalar): IRange.Coords | null;
     private _getValueOrderAscending;
     /**
      * Collects distinct-value frequencies from a grid and returns an instance over them.
@@ -70,7 +79,7 @@ export declare class FrequencyStats implements IRangeStats.IFrequency {
      * (a custom `filterFn` restricts the population in a way nothing else already counts) and the
      * scan's own `visitedCount` is used — exact when not truncated, an undercount when truncated.
      */
-    static fromGrid(grid: ISparseGrid, localCoords: readonly (IRange.Coords | null)[], iteratorOptions: IRange.IteratorOptions | undefined, options: IRangeStats.GetFrequenciesOptions | undefined, defaultCompareFn: (a: Scalar, b: Scalar) => number, blankCount: number, totalCount: number | undefined): FrequencyStats;
+    static fromGrid(grid: ISparseGrid, localCoords: readonly (IRange.Coords | null)[], iteratorOptions: IRange.IteratorOptions | undefined, options: IRangeStats.GetFrequenciesOptions | undefined, defaultCompareFn: (a: Scalar, b: Scalar) => number, blankCount: number, totalCount: number | undefined, skipOrigin?: IRange.CellCoords): FrequencyStats;
     /**
      * Builds an instance directly from an already-merged group map — used by
      * {@link CompositeRangeStats}, which merges its children's own (already-scanned) frequencies

package/types/src/primitives/stats/LookupIndex.d.ts

@@ -0,0 +1,46 @@
+import { IRange, Scalar } from '@sheetxl/primitives';
+import { IListLike, ISparseGrid } from '../../collections';
+/**
+ * An exact-match index over a grid's stored runs, keyed by run identity.
+ *
+ * @remarks
+ * Behind `IRange.indexOf`, and through it `MATCH(…, 0)`, `VLOOKUP(…, FALSE)` and the exact modes
+ * of `XLOOKUP`/`XMATCH`: the shape where one table is read by thousands of lookup cells. Each
+ * stored run is walked once into a map from member key to positions, and the map lives exactly as
+ * long as the run object. Every write REPLACES the runs it touches (`segmentCopyOnWrite.test.ts`),
+ * so a changed run is a miss whose map collects with it, while untouched runs — and every grid
+ * clone and sub-range that shares them — stay warm. Nothing is keyed on the grid, the range or the
+ * pass: none of those is stable across the calls that share a table.
+ *
+ * The key is the hashing side of the `=` rule, the one `UNIQUE` dedupes with: a number as itself,
+ * text through {@link toCompareKey}, a logical as itself. A `Map` keeps the three apart, so `1`,
+ * `"1"` and `TRUE` never collide. Blank, error and rich-data members are never candidates and are
+ * not indexed. Numbers match exactly, as the lookup family compares them; text carries the fold
+ * but not a locale's collation tailorings, the same deviation `UNIQUE` accepts.
+ */
+type Key = number | string | boolean;
+/**
+ * The key a member hashes under, or `undefined` for a member that is never a match.
+ */
+export declare function lookupKey(value: Scalar): Key | undefined;
+/**
+ * The position of `value` along a vector that lies on the grid's own axis, or -1.
+ *
+ * @param values The grid the vector reads.
+ * @param coords One column of a column-oriented grid, or one row of a row-oriented one.
+ * @param isColumn Whether the vector is a column.
+ * @param value The value to find; one {@link lookupKey} answers for.
+ * @param reverse Answer the last position rather than the first.
+ *
+ * @remarks
+ * Runs are asked untrimmed (`overflowRun`), so a run that leaves the vector keeps its identity
+ * and its map: `A2:A100` and `A1:A100` are served by the same index, clipped by position.
+ */
+export declare function indexOfInRuns(values: ISparseGrid<Scalar>, coords: IRange.Coords, isColumn: boolean, value: Scalar, reverse: boolean): number;
+/**
+ * @internal
+ * Whether `run` carries an index. For tests of the cache's lifetime.
+ */
+export declare function isRunIndexed(run: IListLike<Scalar>): boolean;
+export {};
+//# sourceMappingURL=LookupIndex.d.ts.map

package/types/src/primitives/stats/Ranked.d.ts

@@ -10,7 +10,7 @@ import { ISparseGrid } from '../../collections';
  * `includeBlanks` is handled separately: one synthetic `null` candidate is offered per blank
  * cell, capped at `limit` offers (any beyond that can never displace a kept member).
  */
-export declare function collectRanked(grid: ISparseGrid, localCoords: readonly (IRange.Coords | null)[], iteratorOptions: IRange.IteratorOptions | undefined, options: IRangeStats.GetRankedOptions | undefined, defaultCompareFn: (a: Scalar, b: Scalar) => number): readonly Scalar[];
+export declare function collectRanked(grid: ISparseGrid, localCoords: readonly (IRange.Coords | null)[], iteratorOptions: IRange.IteratorOptions | undefined, options: IRangeStats.GetRankedOptions | undefined, defaultCompareFn: (a: Scalar, b: Scalar) => number, skipOrigin?: IRange.CellCoords): readonly Scalar[];
 /**
  * Merges each child's own top-`limit` into the composite's true top-`limit`.
  *

package/types/src/primitives/stats/SortedNumbers.d.ts

@@ -22,11 +22,13 @@ export declare class SortedNumbers implements IRangeStats.ISortedNumbers {
      * Collects the numeric values within `localCoords` from the grid and returns an instance
      * over them (sorted ascending).
      */
-    static fromGrid(grid: ISparseGrid, localCoords: readonly (IRange.Coords | null)[], iteratorOptions: IRange.IteratorOptions | undefined): SortedNumbers;
+    static fromGrid(grid: ISparseGrid, localCoords: readonly (IRange.Coords | null)[], iteratorOptions: IRange.IteratorOptions | undefined, skipOrigin?: IRange.CellCoords): SortedNumbers;
     /** @inheritdoc IRangeStats.ISortedNumbers.getLarge */
     getLarge(k: number): number | null;
     /** @inheritdoc IRangeStats.ISortedNumbers.getSmall */
     getSmall(k: number): number | null;
+    /** Whether a rank names a place at all: `1 <= k <= n`, judged before any truncation. */
+    private _inRank;
     /** @inheritdoc IRangeStats.ISortedNumbers.getPercentile */
     getPercentile(k: number, exclusive?: boolean): number | null;
     /** @inheritdoc IRangeStats.ISortedNumbers.getRankOf */
@@ -43,6 +45,6 @@ export declare class SortedNumbers implements IRangeStats.ISortedNumbers {
      * Collects all numeric values from the range coords and returns them sorted ascending.
      * Called at most once per instance lifetime (result is cached on `_sortedNumbers`).
      */
-    protected static _collectNumbers(grid: ISparseGrid, localCoords: readonly (IRange.Coords | null)[], iteratorOptions: IRange.IteratorOptions | undefined): readonly number[];
+    protected static _collectNumbers(grid: ISparseGrid, localCoords: readonly (IRange.Coords | null)[], iteratorOptions: IRange.IteratorOptions | undefined, skipOrigin?: IRange.CellCoords): readonly number[];
 }
 //# sourceMappingURL=SortedNumbers.d.ts.map

package/types/src/primitives/stats/index.d.ts

@@ -4,4 +4,5 @@ export * from './FrequencyStats';
 export * from './Ranked';
 export * from './ScalarOrder';
 export * from './SortedNumbers';
+export * from './LookupIndex';
 //# sourceMappingURL=index.d.ts.map