handsontable 18.0.0 → 18.1.0-rc7

package/dataMap/metaManager/index.d.ts

@@ -2,6 +2,16 @@ import GlobalMeta from './metaLayers/globalMeta';
 import TableMeta from './metaLayers/tableMeta';
 import ColumnMeta from './metaLayers/columnMeta';
 import CellMeta from './metaLayers/cellMeta';
+import type { CellProperties } from '../../settings';
+/**
+ * The local hooks fired by `MetaManager`, mapped to their callback signatures. The `addLocalHook`,
+ * `removeLocalHook`, and `runLocalHooks` methods are typed against this map so callers get the cell
+ * meta argument inferred automatically instead of `unknown`.
+ */
+interface MetaManagerLocalHooks {
+    afterGetCellMeta: (cellMeta: CellProperties) => void;
+    extendTransientCellMeta: (cellMeta: CellProperties) => void;
+}
 /**
  * With the Meta Manager class, it can be possible to manage with meta objects for different layers in
  * one place. All coordinates used to fetch, updating, removing, or creating rows or columns have to
@@ -57,15 +67,15 @@ export default class MetaManager {
     /**
      * Registers a callback for the given local hook name; returns this instance for chaining.
      */
-    addLocalHook: (key: string, callback: Function) => this;
+    addLocalHook: <K extends keyof MetaManagerLocalHooks>(key: K, callback: MetaManagerLocalHooks[K]) => this;
     /**
      * Unregisters a previously added callback from the given local hook name; returns this instance for chaining.
      */
-    removeLocalHook: (key: string, callback: Function) => this;
+    removeLocalHook: <K extends keyof MetaManagerLocalHooks>(key: K, callback: MetaManagerLocalHooks[K]) => this;
     /**
      * Executes all callbacks registered under the given local hook name, passing any extra arguments.
      */
-    runLocalHooks: (key: string, ...args: unknown[]) => void;
+    runLocalHooks: <K extends keyof MetaManagerLocalHooks>(key: K, ...args: Parameters<MetaManagerLocalHooks[K]>) => void;
     /**
      * Removes all registered local hook callbacks and returns this instance for chaining.
      */
@@ -139,7 +149,48 @@ export default class MetaManager {
         visualRow: number;
         visualColumn: number;
         skipMetaExtension?: boolean;
-    }): Record<string, unknown>;
+    }): CellProperties;
+    /**
+     * Gets a cell meta object for read-only access without retaining it. When the cell already has a
+     * stored meta object (because it carries user-defined or declarative `cell` overrides) that object
+     * is returned; otherwise a transient object inheriting from the column layer is created and NOT
+     * stored. This avoids permanently materializing one cell meta object per scanned cell when iterating
+     * the whole dataset (for example, filtering), where the eager `getCellMeta` would otherwise grow the
+     * meta cache to O(rows × columns). The `afterGetCellMeta` extension is intentionally not run.
+     *
+     * @param {number} physicalRow The physical row index.
+     * @param {number} physicalColumn The physical column index.
+     * @param {object} options Options for the method.
+     * @param {number} options.visualRow The visual row index of the currently requested cell meta object.
+     * @param {number} options.visualColumn The visual column index of the currently requested cell meta object.
+     * @returns {object}
+     */
+    getCellMetaUncached(physicalRow: number, physicalColumn: number, options: {
+        visualRow: number;
+        visualColumn: number;
+    }): CellProperties;
+    /**
+     * Gets a fully-extended cell meta object without retaining it. Unlike `getCellMetaUncached`, the
+     * dynamic extension DOES run - the `beforeGetCellMeta`/`afterGetCellMeta` hooks and the `cells`
+     * function are applied (through the `extendTransientCellMeta` local hook), so hook-driven
+     * properties such as `readOnly`, `hidden`, or `spanned` resolve correctly. Unlike `getCellMeta`,
+     * nothing is stored: when the cell has no persisted meta, the extension runs on a transient object
+     * that is thrown away, so a bulk scan (for example, column-width sampling over the whole row
+     * range) does not permanently materialize one meta object per visited cell. Cells that already
+     * carry stored meta go through the regular memoized `getCellMeta` path. Hook mutations made on a
+     * transient object do not persist - callers that need to write meta must use `setCellMeta`.
+     *
+     * @param {number} physicalRow The physical row index.
+     * @param {number} physicalColumn The physical column index.
+     * @param {object} options Options for the method.
+     * @param {number} options.visualRow The visual row index of the currently requested cell meta object.
+     * @param {number} options.visualColumn The visual column index of the currently requested cell meta object.
+     * @returns {object}
+     */
+    getCellMetaTransient(physicalRow: number, physicalColumn: number, options: {
+        visualRow: number;
+        visualColumn: number;
+    }): CellProperties;
     /**
      * Gets a value (defined by the `key` property) from the cell meta object.
      *
@@ -181,7 +232,7 @@ export default class MetaManager {
      *
      * @returns {object[]}
      */
-    getCellsMeta(): Record<string, unknown>[];
+    getCellsMeta(): CellProperties[];
     /**
      * Returns all cell meta objects that were created during the Handsontable operation but for
      * specific row index.
@@ -189,7 +240,7 @@ export default class MetaManager {
      * @param {number} physicalRow The physical row index.
      * @returns {object[]}
      */
-    getCellsMetaAtRow(physicalRow: number): Record<string, unknown>[];
+    getCellsMetaAtRow(physicalRow: number): CellProperties[];
     /**
      * Returns a flat snapshot of all cell meta properties that were set imperatively through
      * `setCellMeta` (for example, by the user or by the context menu), keyed by physical coordinates.
@@ -216,9 +267,10 @@ export default class MetaManager {
      * Creates one or more rows at specific position.
      *
      * @param {number} physicalRow The physical row index which points from what position the row is added.
+     *   Pass `null` to append at the end.
      * @param {number} [amount=1] An amount of rows to add.
      */
-    createRow(physicalRow: number, amount?: number): void;
+    createRow(physicalRow: number | null, amount?: number): void;
     /**
      * Removes one or more rows from the collection.
      *
@@ -230,9 +282,10 @@ export default class MetaManager {
      * Creates one or more columns at specific position.
      *
      * @param {number} physicalColumn The physical column index which points from what position the column is added.
+     *   Pass `null` to append at the end.
      * @param {number} [amount=1] An amount of columns to add.
      */
-    createColumn(physicalColumn: number, amount?: number): void;
+    createColumn(physicalColumn: number | null, amount?: number): void;
     /**
      * Removes one or more columns from the collection.
      *
@@ -249,3 +302,4 @@ export default class MetaManager {
      */
     clearCache(): void;
 }
+export {};

package/dataMap/metaManager/index.js

@@ -99,6 +99,70 @@ class MetaManager {
         return cellMeta;
     }
     /**
+   * Gets a cell meta object for read-only access without retaining it. When the cell already has a
+   * stored meta object (because it carries user-defined or declarative `cell` overrides) that object
+   * is returned; otherwise a transient object inheriting from the column layer is created and NOT
+   * stored. This avoids permanently materializing one cell meta object per scanned cell when iterating
+   * the whole dataset (for example, filtering), where the eager `getCellMeta` would otherwise grow the
+   * meta cache to O(rows × columns). The `afterGetCellMeta` extension is intentionally not run.
+   *
+   * @param {number} physicalRow The physical row index.
+   * @param {number} physicalColumn The physical column index.
+   * @param {object} options Options for the method.
+   * @param {number} options.visualRow The visual row index of the currently requested cell meta object.
+   * @param {number} options.visualColumn The visual column index of the currently requested cell meta object.
+   * @returns {object}
+   */ getCellMetaUncached(physicalRow, physicalColumn, options) {
+        // Two map lookups on the warm path (vs five for `hasMeta` + `getMeta`), and the miss
+        // fallback stays inline - extracting this expression into a helper regresses the read
+        // through V8 inline-cache pollution.
+        const cellMeta = this.cellMeta.getMetaIfExists(physicalRow, physicalColumn) ?? this.cellMeta.createTransientMeta(physicalColumn);
+        cellMeta.visualRow = options.visualRow;
+        cellMeta.visualCol = options.visualColumn;
+        cellMeta.row = physicalRow;
+        cellMeta.col = physicalColumn;
+        return cellMeta;
+    }
+    /**
+   * Gets a fully-extended cell meta object without retaining it. Unlike `getCellMetaUncached`, the
+   * dynamic extension DOES run - the `beforeGetCellMeta`/`afterGetCellMeta` hooks and the `cells`
+   * function are applied (through the `extendTransientCellMeta` local hook), so hook-driven
+   * properties such as `readOnly`, `hidden`, or `spanned` resolve correctly. Unlike `getCellMeta`,
+   * nothing is stored: when the cell has no persisted meta, the extension runs on a transient object
+   * that is thrown away, so a bulk scan (for example, column-width sampling over the whole row
+   * range) does not permanently materialize one meta object per visited cell. Cells that already
+   * carry stored meta go through the regular memoized `getCellMeta` path. Hook mutations made on a
+   * transient object do not persist - callers that need to write meta must use `setCellMeta`.
+   *
+   * @param {number} physicalRow The physical row index.
+   * @param {number} physicalColumn The physical column index.
+   * @param {object} options Options for the method.
+   * @param {number} options.visualRow The visual row index of the currently requested cell meta object.
+   * @param {number} options.visualColumn The visual column index of the currently requested cell meta object.
+   * @returns {object}
+   */ getCellMetaTransient(physicalRow, physicalColumn, options) {
+        const storedMeta = this.cellMeta.getMetaIfExists(physicalRow, physicalColumn);
+        // The stored path mirrors `getCellMeta` on the already-resolved object instead of delegating
+        // to it - delegation would re-resolve the same cell (two more map lookups per stored cell on
+        // every bulk validate/copy/export scan), and widening `getCellMeta` itself with a pre-resolved
+        // parameter would add a branch to the hottest read path in the grid.
+        if (storedMeta !== undefined) {
+            storedMeta.visualRow = options.visualRow;
+            storedMeta.visualCol = options.visualColumn;
+            storedMeta.row = physicalRow;
+            storedMeta.col = physicalColumn;
+            this.runLocalHooks('afterGetCellMeta', storedMeta);
+            return storedMeta;
+        }
+        const cellMeta = this.cellMeta.createTransientMeta(physicalColumn);
+        cellMeta.visualRow = options.visualRow;
+        cellMeta.visualCol = options.visualColumn;
+        cellMeta.row = physicalRow;
+        cellMeta.col = physicalColumn;
+        this.runLocalHooks('extendTransientCellMeta', cellMeta);
+        return cellMeta;
+    }
+    /**
    * Gets a value (defined by the `key` property) from the cell meta object.
    *
    * @param {number} physicalRow The physical row index.
@@ -181,6 +245,7 @@ class MetaManager {
    * Creates one or more rows at specific position.
    *
    * @param {number} physicalRow The physical row index which points from what position the row is added.
+   *   Pass `null` to append at the end.
    * @param {number} [amount=1] An amount of rows to add.
    */ createRow(physicalRow, amount = 1) {
         this.cellMeta.createRow(physicalRow, amount);
@@ -197,6 +262,7 @@ class MetaManager {
    * Creates one or more columns at specific position.
    *
    * @param {number} physicalColumn The physical column index which points from what position the column is added.
+   *   Pass `null` to append at the end.
    * @param {number} [amount=1] An amount of columns to add.
    */ createColumn(physicalColumn, amount = 1) {
         this.cellMeta.createColumn(physicalColumn, amount);

package/dataMap/metaManager/index.mjs

@@ -84,6 +84,70 @@ class MetaManager {
         return cellMeta;
     }
     /**
+   * Gets a cell meta object for read-only access without retaining it. When the cell already has a
+   * stored meta object (because it carries user-defined or declarative `cell` overrides) that object
+   * is returned; otherwise a transient object inheriting from the column layer is created and NOT
+   * stored. This avoids permanently materializing one cell meta object per scanned cell when iterating
+   * the whole dataset (for example, filtering), where the eager `getCellMeta` would otherwise grow the
+   * meta cache to O(rows × columns). The `afterGetCellMeta` extension is intentionally not run.
+   *
+   * @param {number} physicalRow The physical row index.
+   * @param {number} physicalColumn The physical column index.
+   * @param {object} options Options for the method.
+   * @param {number} options.visualRow The visual row index of the currently requested cell meta object.
+   * @param {number} options.visualColumn The visual column index of the currently requested cell meta object.
+   * @returns {object}
+   */ getCellMetaUncached(physicalRow, physicalColumn, options) {
+        // Two map lookups on the warm path (vs five for `hasMeta` + `getMeta`), and the miss
+        // fallback stays inline - extracting this expression into a helper regresses the read
+        // through V8 inline-cache pollution.
+        const cellMeta = this.cellMeta.getMetaIfExists(physicalRow, physicalColumn) ?? this.cellMeta.createTransientMeta(physicalColumn);
+        cellMeta.visualRow = options.visualRow;
+        cellMeta.visualCol = options.visualColumn;
+        cellMeta.row = physicalRow;
+        cellMeta.col = physicalColumn;
+        return cellMeta;
+    }
+    /**
+   * Gets a fully-extended cell meta object without retaining it. Unlike `getCellMetaUncached`, the
+   * dynamic extension DOES run - the `beforeGetCellMeta`/`afterGetCellMeta` hooks and the `cells`
+   * function are applied (through the `extendTransientCellMeta` local hook), so hook-driven
+   * properties such as `readOnly`, `hidden`, or `spanned` resolve correctly. Unlike `getCellMeta`,
+   * nothing is stored: when the cell has no persisted meta, the extension runs on a transient object
+   * that is thrown away, so a bulk scan (for example, column-width sampling over the whole row
+   * range) does not permanently materialize one meta object per visited cell. Cells that already
+   * carry stored meta go through the regular memoized `getCellMeta` path. Hook mutations made on a
+   * transient object do not persist - callers that need to write meta must use `setCellMeta`.
+   *
+   * @param {number} physicalRow The physical row index.
+   * @param {number} physicalColumn The physical column index.
+   * @param {object} options Options for the method.
+   * @param {number} options.visualRow The visual row index of the currently requested cell meta object.
+   * @param {number} options.visualColumn The visual column index of the currently requested cell meta object.
+   * @returns {object}
+   */ getCellMetaTransient(physicalRow, physicalColumn, options) {
+        const storedMeta = this.cellMeta.getMetaIfExists(physicalRow, physicalColumn);
+        // The stored path mirrors `getCellMeta` on the already-resolved object instead of delegating
+        // to it - delegation would re-resolve the same cell (two more map lookups per stored cell on
+        // every bulk validate/copy/export scan), and widening `getCellMeta` itself with a pre-resolved
+        // parameter would add a branch to the hottest read path in the grid.
+        if (storedMeta !== undefined) {
+            storedMeta.visualRow = options.visualRow;
+            storedMeta.visualCol = options.visualColumn;
+            storedMeta.row = physicalRow;
+            storedMeta.col = physicalColumn;
+            this.runLocalHooks('afterGetCellMeta', storedMeta);
+            return storedMeta;
+        }
+        const cellMeta = this.cellMeta.createTransientMeta(physicalColumn);
+        cellMeta.visualRow = options.visualRow;
+        cellMeta.visualCol = options.visualColumn;
+        cellMeta.row = physicalRow;
+        cellMeta.col = physicalColumn;
+        this.runLocalHooks('extendTransientCellMeta', cellMeta);
+        return cellMeta;
+    }
+    /**
    * Gets a value (defined by the `key` property) from the cell meta object.
    *
    * @param {number} physicalRow The physical row index.
@@ -166,6 +230,7 @@ class MetaManager {
    * Creates one or more rows at specific position.
    *
    * @param {number} physicalRow The physical row index which points from what position the row is added.
+   *   Pass `null` to append at the end.
    * @param {number} [amount=1] An amount of rows to add.
    */ createRow(physicalRow, amount = 1) {
         this.cellMeta.createRow(physicalRow, amount);
@@ -182,6 +247,7 @@ class MetaManager {
    * Creates one or more columns at specific position.
    *
    * @param {number} physicalColumn The physical column index which points from what position the column is added.
+   *   Pass `null` to append at the end.
    * @param {number} [amount=1] An amount of columns to add.
    */ createColumn(physicalColumn, amount = 1) {
         this.cellMeta.createColumn(physicalColumn, amount);

package/dataMap/metaManager/lazyFactoryMap.d.ts

@@ -8,34 +8,28 @@
  *
  * It's essential to notice that the "key" index under which the item was created
  * is volatile. After altering the grid, the "key" index can change.
+ *
+ * Values live in a single native Map keyed by the CURRENT volatile key. Lookups are a
+ * single integer-keyed `Map.get` - a native Map is always a hash table, so far-apart keys
+ * (for example, physical row 999990 on a million-row grid) cannot push the storage into a
+ * slow mode, unlike a sparse array. Key shifts coming from `insert`/`remove` are buffered:
+ * contiguous runs of same-type calls merge into one buffered shift, single-key reads
+ * (`obtain`/`has`/`getIfExists`/`evict`) resolve through the buffer by mapping the requested
+ * key back to its stored key in O(buffered shifts), and only full-view reads
+ * (`size`/`values`/`entries`) apply the buffer in a single O(materialized) re-key pass that
+ * rebuilds the map in its original iteration order - which keeps `values()` returning items
+ * in order of initialization and makes a loop of single-row alters pay one pass per batch,
+ * not one per call. The materialized size is normally viewport-bound thanks to the
+ * render-derived cell meta eviction.
  */
 export default class LazyFactoryMap<V = Record<string, unknown>> {
+    #private;
     /**
      * The data factory function.
      *
      * @type {Function}
      */
     valueFactory: (key: number) => V;
-    /**
-     * An array which contains data.
-     *
-     * @type {Array}
-     */
-    data: (V | undefined)[];
-    /**
-     * An array of indexes where the key of the array is mapped to the value which points to the
-     * specific position of the data array.
-     *
-     * @type {number[]}
-     */
-    index: number[];
-    /**
-     * The collection of indexes that points to the data items which can be replaced by obtaining new
-     * ones. The "holes" are an intended effect of deleting entries.
-     *
-     * @type {Set<number>}
-     */
-    holes: Set<number>;
     /**
      * Initializes the map with the given factory function used to create values for new keys on first access.
      */
@@ -48,64 +42,95 @@ export default class LazyFactoryMap<V = Record<string, unknown>> {
      */
     obtain(key: number): V;
     /**
-     * Inserts an empty data to the map. This method creates an empty space for obtaining
-     * new data.
+     * Checks whether a value for the given key has already been created, without creating one.
+     * Unlike `obtain`, this never triggers the value factory.
+     *
+     * @param {number} key The item key as zero-based index.
+     * @returns {boolean}
+     */
+    has(key: number): boolean;
+    /**
+     * Inserts an empty space for new data. Materialized values stored under keys at or after
+     * the insertion point are re-keyed upwards by `amount`; the inserted keys themselves stay
+     * unmaterialized until the first `obtain` call. The re-keying is buffered (a contiguous run
+     * of inserts merges into one buffered shift) and applied once on the next full-view read, so
+     * a loop of inserts costs one re-key pass, not one per call. When the insertion point sits
+     * at or above every stored key (the common case on a large grid, where only the viewport
+     * band is materialized), nothing is buffered at all.
      *
      * @param {number} key The key as volatile zero-based index at which to begin inserting space for new data.
      * @param {number} [amount=1] Amount of data to insert.
      */
     insert(key: number | null | undefined, amount?: number): void;
     /**
-     * Removes (soft remove) data from "index" and according to the amount of data.
+     * Removes (soft remove) data from the map. Materialized values stored under the removed keys
+     * are dropped (freed for garbage collection) and values under higher keys are re-keyed
+     * downwards by `amount`. The re-keying is buffered (a contiguous run of removes - ascending
+     * or descending - merges into one buffered shift) and applied once on the next full-view
+     * read, so a loop of single-row removes (for example, the per-physical-row calls made by the
+     * data layer when removing many rows at once) costs one re-key pass, not one per call. When
+     * the removal point sits at or above every stored key, nothing is buffered at all.
      *
      * @param {number} key The key as volatile zero-based index at which to begin removing the data.
      * @param {number} [amount=1] Amount data to remove.
      */
     remove(key: number | null | undefined, amount?: number): void;
     /**
-     * Returns the size of the data which this map holds.
+     * Returns the number of materialized values this map currently holds. Keys reserved through
+     * `insert` but never obtained, and keys released through `evict` or `remove`, are not counted.
      *
      * @returns {number}
      */
     size(): number;
     /**
-     * Returns a new Iterator object that contains the values for each item in the LazyMap object.
+     * Returns a new Iterator object that contains the values for each item in the LazyMap object,
+     * in order of value initialization.
      *
      * @returns {Iterator}
      */
     values(): IterableIterator<V>;
     /**
-     * Returns a new Iterator object that contains an array of `[index, value]` for each item in the LazyMap object.
+     * Returns a new Iterator object that contains an array of `[index, value]` for each item in
+     * the LazyMap object, in order of value initialization.
+     *
+     * Mutation-during-iteration contract (also applies to `values()`): the iterator follows
+     * native Map semantics. Releasing the currently visited key through `evict` (as
+     * `CellMeta.evictRow` does) is safe; a value materialized mid-loop through `obtain` of a new
+     * key WILL be visited. Calling `insert`/`remove` mid-loop only buffers the key shift, so the
+     * walk continues undisturbed over the pre-shift view; if another read flushes the buffered
+     * shifts mid-loop, the walk still completes over the pre-shift map it started on.
      *
      * @returns {Iterator}
      */
-    entries(): Iterator<[number, V], any, any> & {
-        [Symbol.iterator](): Iterator<[number, V], any, any> & /*elided*/ any;
-    };
+    entries(): IterableIterator<[number, V]>;
     /**
-     * Clears the map.
+     * Releases the value stored under the given key. The next `obtain` call for that key
+     * re-creates the value through the factory (with a new identity). Unlike `remove`, the
+     * surrounding keys do not shift, so this is safe for values that can be reconstructed
+     * deterministically - for example render-derived cell meta for rows scrolled out of the
+     * viewport. The entry is genuinely deleted, so its memory is freed - there is no leftover
+     * slot. Does nothing when the key has no materialized value.
+     *
+     * @param {number} key The item key as zero-based index.
      */
-    clear(): void;
+    evict(key: number): void;
     /**
-     * Gets storage index calculated from the key associated with the specified value.
+     * Returns the value stored under the given key, or `undefined` when the key has no materialized
+     * value. Unlike `obtain`, it never creates a value through the factory, so it is safe for
+     * read-only existence checks against the current contents.
      *
-     * @param {number} key Volatile zero-based index.
-     * @returns {number} Returns index 0-N or -1 if no storage index found.
+     * @param {number} key The item key as zero-based index.
+     * @returns {*}
      */
-    _getStorageIndexByKey(key: number): number;
+    getIfExists(key: number): V | undefined;
     /**
-     * Gets the key associated with the specified value calculated from storage index.
-     *
-     * @param {number} dataIndex Zero-based storage index.
-     * @returns {number} Returns index 0-N or -1 if no key found.
+     * Clears the map.
      */
-    _getKeyByStorageIndex(dataIndex: number): number;
+    clear(): void;
     /**
      * Makes this object iterable.
      *
      * @returns {Iterator}
      */
-    [Symbol.iterator](): Iterator<[number, V], any, any> & {
-        [Symbol.iterator](): Iterator<[number, V], any, any> & /*elided*/ any;
-    };
+    [Symbol.iterator](): IterableIterator<[number, V]>;
 }