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

package/types/src/collections/ISpatialMap.d.ts

@@ -55,14 +55,21 @@ export interface ISpatialMap<T = any> extends ISpatialQuery<T> {
      */
     insertNonOverlapping(entry: ISpatialMap.Entry<T>, options?: ISpatialMap.InsertNonOverlappingOptions<T>): this;
     /**
-     * TODO - remove this.
+     * {@link insertNonOverlapping} for several entries, merging once for all of them.
      *
-     * @param entries the entries to manage together
-     * @param uuid A unique identifier for the group.
+     * @param entries The entries to add, applied in order.
+     * @param options Options for adding non overlapping options.
+     *
+     * @remarks
+     * Equivalent to calling {@link insertNonOverlapping} for each entry in turn - a later entry wins
+     * over an earlier one where they overlap - but the merge pass runs once over the entries' union
+     * rather than once per entry. Each merge pass searches the entries' neighborhood, so this is
+     * worth reaching for when the entries are near one another, as the pieces of one region are.
      *
-     * @deprecated Use AnchorMap instead
+     * * As with {@link insertNonOverlapping}, `load` is far cheaper when the entries are known not to
+     *   overlap anything already in the map.
      */
-    insertGroup(entries: ISpatialMap.Entry[], uuid: string): this;
+    insertAllNonOverlapping(entries: readonly ISpatialMap.Entry<T>[], options?: ISpatialMap.InsertNonOverlappingOptions<T>): this;
     /**
      * Returns a set of non overlapping inserts and removes that would represent a copy.
      *
@@ -141,10 +148,6 @@ export declare namespace ISpatialMap {
     interface Entry<T = any> extends RangeCoords {
         value?: T;
         uuid?: string;
-        /**
-         * If the entry is the results of a split or a merge.
-         */
-        lastId?: string;
     }
     /**
      * Optional interface for spatial map values that need custom behavior
@@ -330,13 +333,6 @@ export declare namespace ISpatialMap {
          * Called when a group of ranges are merged together.
          */
         onMerged?(onMerges: ISpatialMap.Entry<T>[]): void;
-        /**
-         * Called when a group is updated.
-         *
-         * @param entries All entries in the group.
-         * @param uuid Any params argument passed a modification option.
-         */
-        onGroupUpdate?(entries: ISpatialMap.Entry<T>[], uuid?: string): void;
         /**
          * Called after structure has been updated with for any reason with all
          * inserts and removes.
@@ -355,14 +351,42 @@ export declare namespace ISpatialMap {
          */
         isTrailingEdge?: boolean;
         /**
-         * Indicates if the entries should split when the range is expanding.
+         * Whether an insert that lands INSIDE an entry cuts it in two rather than growing it.
          *
-         * @defaultValue `false`
+         * @defaultValue `false` - the entry expands to cover the inserted cells.
          *
          * @remarks
-         * Examples include formula, comments, and conditional formatting
+         * Insert a column at `B` under an entry on `A1:C3`: `true` leaves `A1:A3` and `C1:D3`, `false`
+         * leaves `A1:D3`. A comment or a hyperlink is per-cell and cuts; a table grows, which is what
+         * a spreadsheet does when you insert a column inside one.
+         *
+         * Only asked of an entry that {@link isSplittable}, and only of an insert.
          */
         isSplitOnExpand?: boolean;
+        /**
+         * Whether an entry may be cut into pieces at all.
+         *
+         * @defaultValue `true`
+         *
+         * @remarks
+         * A property of what the entries ARE, not of any one operation. `false` says this entry is
+         * indivisible: it moves, it grows and it dies, but it never becomes two.
+         *
+         * It decides what a PARTIAL shift does. Insert one cell at `A1`, shifting down, under an entry
+         * on `A1:C3` - only the cells in the band moved, so:
+         *
+         * * splittable, the entry fragments into the part that moved and the part that did not:
+         *   `$A$2:$A$4,$B$1:$C$3`. A style, a comment, a conditional format's applies-to.
+         * * indivisible, the whole entry moves, per axis: `A2:C4`. That is what a formula precedent
+         *   does, and a range listener's anchor is the same kind of thing.
+         *
+         * Both shift. The difference is only whether the entry can come apart.
+         *
+         * TODO - the shift path is the only one that asks. A partial CLEAR fragments an entry through
+         * the model's own `setCoords` without ever reaching here, so an indivisible entry is only
+         * indivisible under a shift.
+         */
+        isSplittable?: boolean;
         /**
          * If `true` then after shift any shift entries will attempt to be merged to their nearest neighbors.
          *
@@ -421,10 +445,15 @@ export declare namespace ISpatialMap {
      */
     interface InsertNonOverlappingOptions<T> {
         /**
-         * Callback function that will be be called on insert.
+         * Decides what each piece of the insert becomes, against what was there.
          *
          * @remarks
-         * If see this will be called for each new entry creation with the original entry.
+         * Called for EVERY piece the insert is cut into, not only the intersecting ones: `orig` is the
+         * entry the piece lands on, or the piece itself with a `null` value where nothing was there.
+         * `adj` is the piece with the inserted value. The returned entry is what the map keeps at
+         * that piece; a `null` value (or `null`) culls it. So a callback that keeps the existing value
+         * must supply one where there is none - `orig.value ?? adj.value` - or the insert silently
+         * lands nowhere. The default replaces the value and keeps the piece.
          */
         onIntersect?: (orig: ISpatialMap.Entry<T>, adj: ISpatialMap.Entry<T>) => ISpatialMap.Entry<T>;
         onUpdates?(inserts: ISpatialMap.Entry<T>[], removes: ISpatialMap.Entry<T>[], spatial: ISpatialMap): void;
@@ -477,12 +506,21 @@ export declare namespace ISpatialMap {
     interface IConflatingEntries<T = any> {
         /**
          * Append a major minor value with an optional value. The value can be left empty if the value is not needed or can be derived from the major and minor.
+         *
+         * Appends are ordered. The last cell may be appended again only if the entries were made to
+         * combine its values; it then leaves the run it was conflated into.
          */
         append: (major: number, minor: number, value?: T) => void;
         /**
          * Returns the conflated entries. If `merge` is `true` then adjacent entries will be merged into a single entry with a range that covers both entries. If `false` then each entry will be returned as-is.
          */
         done: (merge?: boolean) => ISpatialMap.Entry<T>[];
+        /**
+         * The entry appended so far that covers a position, before {@link done}.
+         *
+         * @returns `undefined` if nothing was appended there.
+         */
+        find: (major: number, minor: number) => ISpatialMap.Entry<T> | undefined;
     }
 }
 export interface ISpatialQuery<T = any> {

package/types/src/collections/ImmutableList.d.ts

@@ -23,6 +23,8 @@ export declare class ImmutableList<T> implements IReadableList<T> {
     private _length;
     /** Single-entry cache of the last-accessed run, to skip binary search on sequential reads. */
     private _runCache;
+    /** See {@link getUniformRuns}. `undefined` = not looked yet, `null` = looked, there are none. */
+    private _uniform;
     constructor(values?: T[] | IListLike<T>);
     /**
      * Returns the value at a given index.
@@ -42,6 +44,32 @@ export declare class ImmutableList<T> implements IReadableList<T> {
     /** {@inheritDoc IReadableList.length} */
     get length(): number;
     [Symbol.iterator](): IterableIterator<T>;
+    /**
+     * The stretches of this list that hold ONE value throughout, as `[from, to, value]` triples in
+     * index order, or `null` when there are none.
+     *
+     * @remarks
+     * A stretch is a period-1 `RepeatingList` (`isIRepeatingList`, the house brand convention)
+     * backing the whole list or one of its slices: a run written as "this value, this many times"
+     * stays recognizable after the list has been sliced or merged with its neighbors, so a reader
+     * can act on the stretch once instead of asking `at` for every position. Anything else — an
+     * array, a cyclic repeat — is not a stretch and is read per position. Computed once and held:
+     * the list is immutable.
+     */
+    getUniformRuns(): readonly (readonly [from: number, to: number, value: T])[] | null;
+    /**
+     * Calls `fn` for each stretch of `list` that one leaf list backs, in index order, over
+     * `[from, to]` (inclusive). In a stretch `[stretchFrom, stretchTo]`, the value at list index `i`
+     * is `leaf.at(leafFrom + i - stretchFrom)`. Anything that is not an `ImmutableList` is its own
+     * leaf.
+     *
+     * @remarks
+     * For a reader that can do better with a leaf than ask `at` of the wrapper: a typed leaf's
+     * buffer, a repeat's one value.
+     */
+    static forEachLeaf<T>(list: IListLike<T>, fn: (leaf: IListLike<T>, leafFrom: number, stretchFrom: number, stretchTo: number) => void, from?: number, to?: number): void;
+    /** {@link forEachLeaf} over `[from, to]` of `list`, reported `shift` further on. */
+    private static _forEachLeaf;
     /** {@inheritDoc IReadableList.isIReadableList} */
     get isIReadableList(): true;
     /** {@inheritDoc IList.isIList} */

package/types/src/collections/MixedTypedArrayList.d.ts

@@ -1,140 +1,200 @@
-import { IListLike } from './IList';
+import { IList, IListLike } from './IList';
 /**
- * Stores mixed value types in an ArrayBuffer or a SharedArrayBuffer.
+ * An immutable run of mixed scalar values in ONE `ArrayBuffer` or `SharedArrayBuffer`.
  *
- * Enable more efficient storage of mixed types in a single array.
- * Supports fully shared between threads without copy.
+ * Numbers, booleans and blanks are stored natively; strings and errors as `int32` ids that a
+ * {@link MixedTypedArrayList.Codec} resolves. The buffer is the whole list: another thread that
+ * receives its {@link MixedTypedArrayList.Handle} (and has the same codec) reads it without a copy.
  *
  * @remarks
- * * Implements {@link IListLike} — expects all values to be immutable.
- * * Supports numbers (int32, float32, float64, bigint), booleans, null, and undefined natively.
- * * Strings and errors are stored as ordinal references; provide `getCoercedValue` to resolve them.
- * * Custom types (128–255) are supported via `getCoercedKey` / `getCoercedValue` callbacks.
+ * Layout, for `length` values at `width` 4 or 8 bytes:
+ * - the value slots, `length * width` bytes, absent when no value needs one (booleans and blanks);
+ * - then one type byte per value, absent when every value is of one type.
+ *
+ * The width is 4 when no value is a non-int32 number, else 8. At width 8 an `int32` (int, string
+ * id, error code) lives in the low word of its slot and a double in the whole slot.
+ *
+ * Implements {@link IListLike}: `at` answers `undefined` past the end and `null` for a blank.
+ * Slicing and concatenation are `ImmutableList`'s, logically, over any list.
+ *
+ * Create with {@link MixedTypedArrayList.fromArray}; rebuild from a handle with the constructor.
  */
-export declare class MixedTypedArrayList<T = any> implements IListLike<T> {
-    private _l;
-    private _at;
-    private _dt;
-    private _a32;
-    private _a64;
-    private _cv;
-    private _vt;
-    private _vi32;
-    private _vi64;
-    private _vf32;
-    private _vf64;
-    constructor(options: MixTypedArrayListConstructorOptions);
+export declare class MixedTypedArrayList<T = any> implements IList<T> {
+    private readonly _l;
+    private readonly _w;
+    /** `0` at width 4, `1` at width 8: the int32 index is `(i << _sh) + _lo`. */
+    private readonly _sh;
+    /** The word an int32 occupies at width 8: `0` little-endian, `1` big-endian. */
+    private readonly _lo;
+    private readonly _dt;
+    private readonly _m;
+    private readonly _buf;
+    private readonly _vi;
+    private readonly _vf;
+    private readonly _t;
+    private readonly _c;
+    private _v;
     /**
-     * Returns constructor options that can used to recreate the MixedTypedArrayList.
+     * Rebuilds a list over a handle's buffer, without copying it.
+     *
+     * @param handle The handle, from {@link getHandle} or from another thread.
+     * @param codec Required when the run holds strings or errors.
      */
-    getConstructorOptions(): MixTypedArrayListConstructorOptions;
+    constructor(handle: MixedTypedArrayList.Handle, codec?: MixedTypedArrayList.Codec<T> | null);
     /** {@inheritDoc IListLike.at} */
     at(index: number): T | undefined;
-    /** {@inheritDoc IListLike.toArray} */
-    toArray(maxLength: number): T[];
+    /**
+     * The type code of the value at `index` (see {@link MixedTypedArrayList.Type}), or `-1` past
+     * the end.
+     */
+    typeAt(index: number): number;
+    /**
+     * The types the list may hold, as a bitmask of `1 << Type`. It never omits a type a value
+     * holds, so a missing bit answers "none here" without a scan; a set bit may name a type no
+     * value holds.
+     */
+    get typeMask(): number;
+    /**
+     * The typed arrays under the list, for a loop over a stretch of it without `at`: the type of
+     * index `i` is `types[i]` (or `defaultType` when `types` is `null`), an int32, string id or
+     * error code is `ints[(i << intShift) + intOffset]`, and a double is `doubles[i]`.
+     */
+    getViews(): MixedTypedArrayList.Views;
     /** {@inheritDoc IListLike.length} */
     get length(): number;
-    get [Symbol.toStringTag](): string;
-    toString(): string;
-    protected static _createArrayBuffer(length: number): ArrayBufferLike;
+    /** {@inheritDoc IList.isIList} */
+    get isIList(): true;
     /**
-     * Creates a MixedTypedArrayList from an array.
-     *
-     * @param array The array to convert.
-     * @param getCoercedKey A function that returns a key for a complex value.
-     * @param getCoercedValue A function that returns a coerced value for a given key.
-     * @param getCoerceType A function that returns a type for a given value.
-     * @returns A MixedTypedArrayList.
-     *
+     * {@inheritDoc IListLike.fromArray}
      * @remarks
-     * - `getCoercedKey` will generally be a map id.
+     * A plain list: this is asked for small merges (`ImmutableList.concat`), below the length a
+     * typed list is worth.
      */
-    static fromArray<T = any>(array: T[], getCoercedKey?: (type: number, value: T) => number, getCoercedValue?: (type: number, key: number) => T, getCoerceType?: (value: T) => number, threshold64?: number): MixedTypedArrayList;
-}
-export interface MixTypedArrayListConstructorOptions<T = any> {
+    fromArray(arr: T[]): IListLike<T>;
+    /** The bytes a value occupies: `4` or `8`. */
+    get width(): number;
+    /** Whether the buffer is a `SharedArrayBuffer`. */
+    get isShared(): boolean;
     /**
-     * The length of the array.
+     * The values as an `Array`.
+     * @param maxLength At most this many, from the start.
      */
-    length: number;
+    toArray(maxLength?: number): T[];
     /**
-      * The array used for storing types.
-      *
-      * @remarks
-      * This is the default type if types is not provided.
-      */
-    type: number;
-    /**
-     * The array used for storing types.
-     *
-     * @remarks
-     * This must be a Uint8Array. This or type must be provided.
+     * What rebuilds this list: the buffer and its shape. Post it to another thread (a shared
+     * buffer is shared; an `ArrayBuffer` is copied, or transferred and then unusable here).
      */
-    types?: ArrayBufferLike | null;
+    getHandle(): MixedTypedArrayList.Handle;
+    get [Symbol.toStringTag](): string;
+    toString(): string;
     /**
-     * Stores 32bit values.
-     *
-     * @remarks
-     * If this is not provided then all values stored in values64.
-     * * Must be 32bit aligned
+     * Whether `SharedArrayBuffer` can be allocated here: it exists, and the page is cross-origin
+     * isolated where that applies.
      */
-    values32?: ArrayBufferLike | null;
+    static get isSharedSupported(): boolean;
     /**
-     * Stores 64 bit overflow values or all 64 bit values if is64Bit is `true`.
+     * Encodes an array of values.
      *
-     * @remarks
-     * * This behave different depending on if the values32 is provided.
-     * * * values32 is provided - This stores 32 bit values and 32 bit references to 64 bit values.
-     * * * values32 is NOT provided - Then this is used for all values and values32 is not used.
-     * * Must be 64bit aligned
+     * @param values The values, or a scratch holding them first (`options.length`). `undefined` is
+     * stored as a blank. Never retained.
+     * @param codec Resolves strings and errors. Without one a run holding either cannot be encoded.
+     * @param options Allocation and the hints a writer that saw the values already has.
+     * @returns The list, or `null` when a value cannot be encoded: a rich value, or a string or
+     * error with no codec. Nothing is allocated in that case.
      */
-    values64?: ArrayBufferLike | null;
+    static fromArray<T = any>(values: readonly T[], codec?: MixedTypedArrayList.Codec<T> | null, options?: MixedTypedArrayList.FromArrayOptions): MixedTypedArrayList<T> | null;
     /**
+     * Encodes values that are already codes and numbers: a load path that has string ids and
+     * error codes in hand writes them without resolving a single string.
      *
-     * Returns a value for a given type The default implementation auto coerces ints/floats/boolean and 'null'.
-     *
-     * @param type An 8bit number. Will always be between 0 and 255.
-     * @param key The key as either a 32bit or 64bit integer.
-     * @returns Returns a coerced value.
-     *
-     * @remarks
-     * This is used for returning string lookup, error lookup, or custom.
+     * @param codes The {@link MixedTypedArrayList.Type} of each value. Never `Rich`.
+     * @param values Per position: the int, double, string id or error code; ignored for a boolean
+     * or a blank.
+     * @param codec For reads; the run is written as given.
      */
-    getCoercedValue?: ((type: number, key: number) => T) | null;
+    static fromEncoded<T = any>(codes: Uint8Array, values: ArrayLike<number>, codec?: MixedTypedArrayList.Codec<T> | null, options?: MixedTypedArrayList.FromArrayOptions): MixedTypedArrayList<T>;
 }
 /**
- * Defines the list of Known valid type codes for a MixedTypedArrayList.
- *
- * @remarks
- * MixedTypedArray stores a type using an Uint8Array. The first
- * 127 bits are reserved for known types. The last 128-255 are
- * reserved for custom types.
- *
+ * {@inheritDoc MixedTypedArrayList}
  * @see
- * {@link MixTypedArrayListConstructorOptions.coerceType}
- */
-export declare const KnownType: {
-    readonly Null: 0;
-    readonly Boolean: 1;
-    readonly Integer: 2;
-    readonly Float: 3;
-    readonly Integer64: 4;
-    readonly Float64: 5;
-    readonly String: 6;
-    readonly Error: 7;
-    readonly PosInfinity: 16;
-    readonly NegInfinity: 17;
-    readonly NaN: 18;
-    readonly MaxSafeInteger: 19;
-    readonly MinSafeInteger: 20;
-    readonly Undefined: 15;
-    readonly Unknown: 127;
-};
-/**
- * Return a 8 bit int that represents the type to using in the type array.
+ * ### **Class**
  *
- * @param value The value of the type. Only the type is used
- * @param custom If provided this will be called if the type is not well known. Must return a value between '128' and '255'.
- * @returns a number representing a type between '0' and '255'.
+ * {@link MixedTypedArrayList}
  */
-export declare function getBuiltinCoerceType<T = any>(value: T, custom?: (T: any) => number): number;
+export declare namespace MixedTypedArrayList {
+    /**
+     * The type codes, one byte each. A boolean or a blank is its code alone and has no value slot.
+     */
+    const Type: {
+        readonly Blank: 0;
+        readonly False: 1;
+        readonly True: 2;
+        readonly Int32: 3;
+        readonly Float64: 4;
+        readonly String: 5;
+        readonly Error: 6;
+        /** Reserved. A run holding a rich value is not encoded. */
+        readonly Rich: 7;
+    };
+    /**
+     * Resolves what the buffer stores as an id: strings and errors, both ways.
+     */
+    interface Codec<T = any> {
+        /** Whether an object value is an error (anything else is rich, and not encoded). */
+        isError(value: object): boolean;
+        /** The id a string is stored as; the same string must give the same id. */
+        encodeString(value: string): number;
+        /** The string for an id. */
+        decodeString(id: number): T;
+        /** The code an error is stored as. */
+        encodeError(value: T): number;
+        /** The error for a code. */
+        decodeError(code: number): T;
+    }
+    /**
+     * What rebuilds a list over its buffer. Passes through `structuredClone` and `postMessage`.
+     */
+    interface Handle {
+        buffer: ArrayBufferLike;
+        length: number;
+        width: 4 | 8;
+        /** The one type, when `hasTypes` is `false`. */
+        defaultType: number;
+        /** {@inheritDoc MixedTypedArrayList.typeMask} */
+        typeMask: number;
+        /** Whether a type byte per value follows the slots. */
+        hasTypes: boolean;
+        /** Whether any value has a slot; `false` for a run of booleans and blanks. */
+        hasSlots: boolean;
+    }
+    /** {@inheritDoc MixedTypedArrayList.getViews} */
+    interface Views {
+        readonly types: Uint8Array | null;
+        readonly defaultType: number;
+        readonly ints: Int32Array;
+        readonly doubles: Float64Array | null;
+        readonly intShift: 0 | 1;
+        readonly intOffset: 0 | 1;
+    }
+    interface FromArrayOptions {
+        /**
+         * Allocate a `SharedArrayBuffer` when supported.
+         * @defaultValue false
+         */
+        shared?: boolean;
+        /**
+         * Encode only the first `length` values: the input is a writer's reused scratch, longer than
+         * the run.
+         * @defaultValue the input's length
+         */
+        length?: number;
+        /**
+         * The types the values hold, as a bitmask of `1 << Type`, from a writer that saw them. Not
+         * validated: a wrong mask encodes wrong values, and it is kept as
+         * {@link MixedTypedArrayList.typeMask}. A single-type mask skips the type bytes and the
+         * classification; any mask sets the width before allocating.
+         */
+        seen?: number;
+    }
+}
 //# sourceMappingURL=MixedTypedArrayList.d.ts.map

package/types/src/collections/OverlappingRangeIterator.d.ts

@@ -1,4 +1,4 @@
-import { RangeAxis, RangeCoords, CellCoords, RangeCoordValue } from '@sheetxl/utils';
+import { RangeAxis, CellCoords, RangeCoords, RangeCoordValue } from '@sheetxl/utils';
 /**
  * Iterate over a collection of overlapping RangeCoords.
  *
@@ -33,9 +33,10 @@ export declare namespace OverlappingRange {
          * @defaultValue `undefined` (Creates new instances for each iterator)
          *
          * @remarks
-         * - **Performance:** Setting this to `true` can drastically improve performance for large ranges,
-         *   but it will modify the original range data.
-         * - **Safety:**  If you need to preserve the original range data, set this to `false`.
+         * - **Performance:** Removes the per-step allocations (the result, range, cell, and overlaps
+         *   objects are mutated in place), which matters for large sweeps.
+         * - **Safety:** A returned intersection is only valid until the next call to `next` — copy
+         *   anything that is retained. Pass an `IteratorResult` to supply the reused buffer yourself.
          */
         reuseIterator?: boolean | IteratorResult<OverlappingRange.Intersection>;
     }
@@ -61,22 +62,17 @@ export declare namespace OverlappingRange {
         overlaps: RangeCoordValue[];
     }
     type Iterator = ESIterator<Intersection, Intersection, CellCoords>;
+    /**
+     * An adapter over the shared line-sweep engine (`_RangeSweep`): the ranges become pieces (their
+     * input order is the stable order), the sweep partitions them into non-overlapping regions, and
+     * each step is handed out as a fresh {@link Intersection}.
+     */
     class IteratorInstance implements Iterator, IterableIterator<Intersection> {
-        private _isColumn;
+        private _sweep;
         private _isByCell;
-        private _isReverse;
-        private _cursor;
+        private _cellComparator;
+        private _lastCell;
         private _reuse;
-        private _localReuse;
-        private _eventsMajor;
-        private _eventMajorIndex;
-        private _majorStart;
-        private _majorEnd;
-        private _eventsMinor;
-        private _eventsMinorIterator;
-        private _eventMinorPeek;
-        private _minorStart;
-        private _minorEnd;
         constructor(ranges: readonly RangeCoordValue[], options?: IteratorOptions);
         /**
          * Returns the next Intersection as a IteratorResult.

package/types/src/collections/RepeatingList.d.ts

@@ -13,8 +13,15 @@ export declare class RepeatingList<T> implements IList<T> {
     toArray(maxLength?: number): T[];
     /** {@inheritDoc IListLike.length} */
     get length(): number;
+    /**
+     * The length of the repeated list — the period. A period of `1` is one value however long, so a
+     * consumer that would otherwise scan every position can read `at(0)` once.
+     */
+    getPeriod(): number;
     get [Symbol.toStringTag](): string;
     /** {@inheritDoc IList.isIList} */
     get isIList(): true;
+    /** For runtime type checking. */
+    get isIRepeatingList(): true;
 }
 //# sourceMappingURL=RepeatingList.d.ts.map

package/types/src/collections/ScalarGrid.d.ts

@@ -0,0 +1,50 @@
+import { Direction, RangeAxis, CellCoords, RangeCoords } from '@sheetxl/utils';
+import { Tuple } from './Tuple';
+import { IGrid } from './IGrid';
+import { ISparseGrid } from './ISparseGrid';
+/**
+ * A grid holding one value at (0,0) — the backing of a direct-scalar box.
+ *
+ * @remarks
+ * Every scalar handed to a range-typed parameter (`IF`'s branches, `AND`/`OR`/`MIN`/`MAX`
+ * arguments) is boxed into a 1x1 range, and most boxes are only ever read back out again by the
+ * consumer (`getValueAt(0, 0)`), so building a full {@link SparseGrid} — a major list, a minor
+ * list, a run — for each was the single largest allocation in a recalculation: ~100K per pass on
+ * a 28K-formula template. This answers the reads a box gets natively and holds no structure at
+ * all; the first call that needs one (iteration, a write, a copy) materializes a real
+ * `SparseGrid` and delegates to it from then on, so every other behavior is exactly the grid's.
+ */
+export declare class ScalarGrid<T = any> implements ISparseGrid<T> {
+    private _value;
+    private _axis;
+    private _maxCoords;
+    /** The real grid, once anything beyond a point read was asked for. */
+    private _grid;
+    constructor(value: T, options?: ScalarGrid.ConstructorOptions);
+    private _materialize;
+    getValueAt(row: number, column: number): T;
+    getCount(): number;
+    getCoords(): RangeCoords | null;
+    getAxis(): RangeAxis;
+    getMaxCoords(): RangeCoords | null;
+    clone(cloneKey?: any): this;
+    cloneEmpty(cloneKey?: any): this;
+    setValues(values: Tuple.GridTuple<T>): this;
+    setValueAt(row: number, column: number, value: T): void;
+    getValues(coords?: RangeCoords): Tuple.Region<T> | null;
+    entries(options?: IGrid.IteratorOptions): IGrid.EntryIterator<T>;
+    keys(options?: IGrid.IteratorOptions): IGrid.KeyIterator;
+    values(options?: IGrid.IteratorOptions): IGrid.ValueIterator;
+    getRuns(options?: ISparseGrid.RunIteratorOptions): ISparseGrid.RunIterableIterator<T>;
+    delete(coords: RangeCoords | null): boolean;
+    clear(): void;
+    shift(coords: RangeCoords, direction: Direction): boolean;
+    copyTo(destination: IGrid, topLeft: CellCoords, from: RangeCoords): void;
+}
+export declare namespace ScalarGrid {
+    interface ConstructorOptions {
+        axis?: RangeAxis;
+        maxCoords?: RangeCoords;
+    }
+}
+//# sourceMappingURL=ScalarGrid.d.ts.map

package/types/src/collections/SparseGrid.d.ts

@@ -39,7 +39,7 @@ export declare class SparseGrid<T = any> implements ISparseGrid<T> {
     /** {@inheritDoc IGrid.setValues} */
     setValues(values: Tuple.GridTuple<T>): this;
     /** {@inheritDoc IGrid.getValues} */
-    getValues(coords?: RangeCoords): Tuple.BoundedTuples<T> | null;
+    getValues(coords?: RangeCoords): Tuple.Region<T> | null;
     private _updateCountAndCoords;
     /** {@inheritDoc IGrid.clear} */
     clear(): void;