IndexMapper

Index mapper stores, registers and manages the indexes on the basis of calculations collected from the subsidiary maps.
It should be seen as a single source of truth (regarding row and column indexes, for example, their sequence, information if they are skipped in the process of rendering (hidden or trimmed), values linked to them)
for any operation that considers CRUD actions such as insertion, movement, removal etc, and is used to properly calculate physical and visual indexes translations in both ways.
It has a built-in cache that is updated only when the data or structure changes.

Physical index is a type of an index from the sequence of indexes assigned to the data source rows or columns
(from 0 to n, where n is number of the cells on the axis of data set).
Visual index is a type of an index from the sequence of indexes assigned to rows or columns existing in DataMap (from 0 to n, where n is number of the cells on the axis of data set).
Renderable index is a type of an index from the sequence of indexes assigned to rows or columns whose may be rendered (when they are in a viewport; from 0 to n, where n is number of the cells renderable on the axis).

There are different kinds of index maps which may be registered in the collections and can be used by a reference.
They also expose public API and trigger two local hooks such as init (on initialization) and change (on change).

These are: IndexesSequence, PhysicalIndexToValueMap, HidingMap, and TrimmingMap.

Methods

executeBatchOperations(wrappedOperations)

Execute batch operations with updating cache when necessary. As effect, wrapped operations will be executed and
cache will be updated at most once (cache is updated only when any cached index has been changed).

Parameters:
Name Type Description
wrappedOperations function

Batched operations wrapped in a function.

getFirstNotHiddenIndex(fromVisualIndex, incrementBy, searchAlsoOtherWayAround, indexForNextSearch){number|null}

Search for the first visible, not hidden index (represented by a visual index).

Parameters:
Name Type Default Description
fromVisualIndex number

Visual start index. Starting point for finding destination index. Start point may be destination
point when handled index is NOT hidden.

incrementBy number

We are searching for a next visible indexes by increasing (to be precise, or decreasing) indexes.
This variable represent indexes shift. We are looking for an index:

  • for rows: from the left to the right (increasing indexes, then variable should have value 1) or
    other way around (decreasing indexes, then variable should have the value -1)
  • for columns: from the top to the bottom (increasing indexes, then variable should have value 1)
    or other way around (decreasing indexes, then variable should have the value -1).
searchAlsoOtherWayAround boolean false

The argument determine if an additional other way around search should be
performed, when the search in the first direction had no effect in finding visual index.

indexForNextSearch number

Visual index for next search, when the flag is truthy.

Returns: {number|null} Visual column index or null.

getIndexesSequence(){Array}

Get sequence of indexes.

Returns: {Array} Physical indexes.

getNotHiddenIndexes(readFromCache){Array}

Get all NOT hidden indexes.

Note: Indexes marked as hidden are included in a DataMap, but aren't rendered.

Parameters:
Name Type Default Description
readFromCache boolean true optional

Determine if read indexes from cache.

Returns: {Array} List of physical indexes. Please keep in mind that index of this native array IS NOT a "visual index".

getNotHiddenIndexesLength(){number}

Get length of all NOT hidden indexes.

Note: Indexes marked as hidden are included in a DataMap, but aren't rendered.

Returns: {number}

getNotTrimmedIndexes(readFromCache){Array}

Get all NOT trimmed indexes.

Note: Indexes marked as trimmed aren't included in a DataMap and aren't rendered.

Parameters:
Name Type Default Description
readFromCache boolean true optional

Determine if read indexes from cache.

Returns: {Array} List of physical indexes. Index of this native array is a "visual index",
value of this native array is a "physical index".

getNotTrimmedIndexesLength(){number}

Get length of all NOT trimmed indexes.

Note: Indexes marked as trimmed aren't included in a DataMap and aren't rendered.

Returns: {number}

getNumberOfIndexes(){number}

Get number of all indexes.

Returns: {number}

getPhysicalFromRenderableIndex(renderableIndex){null|number}

Get a physical index corresponding to the given renderable index.

Parameters:
Name Type Description
renderableIndex number

Renderable index.

Returns: {null|number}

getPhysicalFromVisualIndex(visualIndex){number|null}

Get a physical index corresponding to the given visual index.

Parameters:
Name Type Description
visualIndex number

Visual index.

Returns: {number|null} Returns translated index mapped by passed visual index.

getRenderableFromVisualIndex(visualIndex){null|number}

Get a renderable index corresponding to the given visual index.

Parameters:
Name Type Description
visualIndex number

Visual index.

Returns: {null|number}

getRenderableIndexes(readFromCache){Array}

Get list of physical indexes (respecting the sequence of indexes) which may be rendered (when they are in a viewport).

Parameters:
Name Type Default Description
readFromCache boolean true optional

Determine if read indexes from cache.

Returns: {Array} List of physical indexes. Index of this native array is a "renderable index",
value of this native array is a "physical index".

getRenderableIndexesLength(){number}

Get length of all NOT trimmed and NOT hidden indexes.

Returns: {number}

getVisualFromPhysicalIndex(physicalIndex){number|null}

Get a visual index corresponding to the given physical index.

Parameters:
Name Type Description
physicalIndex number

Physical index to search.

Returns: {number|null} Returns a visual index of the index mapper.

getVisualFromRenderableIndex(renderableIndex){null|number}

Get a visual index corresponding to the given renderable index.

Parameters:
Name Type Description
renderableIndex number

Renderable index.

Returns: {null|number}

initToLength(length)

Set default values for all indexes in registered index maps.

Parameters:
Name Type Description
length number optional

Destination length for all stored index maps.

isHidden(physicalIndex){boolean}

Get whether index is hidden. Index marked as hidden is included in a DataMap, but isn't rendered.

Parameters:
Name Type Description
physicalIndex number

Physical index.

Returns: {boolean}

isTrimmed(physicalIndex){boolean}

Get whether index is trimmed. Index marked as trimmed isn't included in a DataMap and isn't rendered.

Parameters:
Name Type Description
physicalIndex number

Physical index.

Returns: {boolean}

moveIndexes(movedIndexes, finalIndex)

Move indexes in the index mapper.

Parameters:
Name Type Description
movedIndexes number | Array

Visual index(es) to move.

finalIndex number

Visual index being a start index for the moved elements.

registerMap(uniqueName, indexMap){IndexMap}

Register map which provide some index mappings. Type of map determining to which collection it will be added.

Parameters:
Name Type Description
uniqueName string

Name of the index map. It should be unique.

indexMap IndexMap

Registered index map updated on items removal and insertion.

Returns: {IndexMap}

setIndexesSequence(indexes)

Set completely new indexes sequence.

Parameters:
Name Type Description
indexes Array

Physical indexes.

unregisterMap(name)

Unregister a map with given name.

Parameters:
Name Type Description
name string

Name of the index map.

Class: IndexMapper