Collection

A class which encapsulates a keyed, filterable, sortable collection of objects. Entries may not be atomic data types such as string or number.

The entries are keyed by their id which is determined by interrogating the idProperty.

To filter a Collection, add a CollectionFilter using the addFilter method. A Filter config object may be specified here which will be promoted to a CollectionFilter instance.

To sort a Collection, add a CollectionSorter using the addSorter method. A Sorter config object may be specified here which will be promoted to a CollectionSorter instance.

Useful configs and functions

Config / Function	Description
idProperty	Property name used as the item key
add	Add items to the collection
remove	Remove items from the collection
get	Get an item by its id
addFilter	Add a filter to the collection
addSorter	Add a sorter to the collection

Configs

Configs are options you supply in a configuration object when creating an instance of this class

autoFilter : Booleantrue

Automatically apply filters on item add.
extraKeys : String[]/Object[]
Specify the names or index configs of properties which are to be indexed for fast lookup.

Index configs use the format { property : string, unique : boolean }. Unique indices stores one index per entry, non-unique stores a Set. If left out, unique defaults to true
- property : String
  
  Property to index by
- unique : Booleantrue
  
  true for unique keys (~primary keys), false for non-unique keys (~foreign keys)
idProperty : Stringid

Specify the name of the property of added objects which provides the lookup key

Has a corresponding runtime idProperty property.
sorters : CollectionSorterConfig[]

A Sorter, or Sorter config object, or an array of these, to use to sort this Collection.

Has a corresponding runtime sorters property.

Properties

Properties are getters/setters or publicly accessible variables on this class

addedValues : Object[]

private

READONLY

The set of values added to this Collection since the last sort or replaceValues operation.
allValues : Object[]

READONLY

The set of all values of this Collection regardless of filters applied.
count : Number

READONLY

The number of items in this collection. Note that this honours filtering. See totalCount;
filterFunction : Function

READONLY

A filter function which encapsulates the Filters for this Collection.
filteredValues : Object[]

private

READONLY

The set of filtered values of this Collection (those matching the current filters).
filters : Collection

READONLY

The Collection of Filters for this Collection.
generation : Number

READONLY

A counter which is incremented whenever the Collection is mutated in a meaningful way.

If a splice call results in no net replacement, removal or addition, then the generation will not be incremented.
idProperty : String

The property name used to extract item ids from added objects.

Has a corresponding idProperty config.
isFiltered : Boolean

READONLY

A flag which is true if this Collection has active filters.
isSorted : Boolean

READONLY

A flag which is true if this Collection has active sorters.
sortFunction : Function

READONLY

A sorter function which encapsulates the Sorters for this Collection.
sorters : Collection

The Collection of Sorters for this Collection.

Has a corresponding sorters config.
totalCount : Number

READONLY

The number of items in this collection regardless of filtering.
values : Object[]

The set of values of this Collection. If this Collection isFiltered, this yields the filtered data set.

Setting this property replaces the data set.

Functions

Functions are methods available for calling on the class

add( ...items )

Adds items to this Collection. Multiple new items may be passed.

By default, new items are appended to the existing values.

Any sorters sorters present are re-run.

Any filters filters present are re-run.

Note that if application functionality requires add and remove, the splice operation is preferred as it performs both operations in an atomic manner
addFilter( filter )
: CollectionFilter
Adds a Filter to the Collection of Filters which are operating on this Collection.

A Filter may be an specified as an instantiated CollectionFilter, or a config object for a CollectionFilter of the form
```
{
    property : 'age',
    operator : '>=',
    value    : 21
}
```
Note that by default, a Filter replaces a Filter with the same property to make it easy to change existing Filters. A Filter's id is its property by default. You can avoid this and add multiple Filters for one property by configuring Filters with ids.

A Filter may also be specified as a function which filters candidate objects eg:
```
candidate => candidate.customerDetails.age >= 21
```
addIndex( indexConfig )

internal

Adds a lookup index for the passed property name or index config. The index is built lazily when an index is searched
addIndexEntry( item, propertyName, value )

private

Add a new entry to an index, and if filtering is used also to the filtered index.
addSorter( sorter )
: CollectionSorter
Adds a Sorter to the Collection of Sorters which are operating on this Collection.

A Sorter may be specified as an instantiated CollectionSorter, or a config object for a CollectionSorter of the form
```
{
    property  : 'age',
    direction : 'desc'
}
```
Note that by default, a Sorter replaces a Sorter with the same property to make it easy to change existing Sorters. A Sorter's id is its property by default. You can avoid this and add multiple Sorters for one property by configuring Sorters with ids.

A Sorter may also be specified as a function which compares two objects eg:
```
(lhs, rhs) => lhs.customerDetails.age - rhs.customerDetails.age
```
addToIndices( item )

private

Add an item to all indices
changeId( item, newId )

Change the id of an existing member by mutating its idProperty.
clear( )

Clears this collection.
equals( other, map )
: Boolean

Compares the content of this Collection with the content of the passed Collection or with the passed array. Order insensitive. This returns true if the two objects passed contain the same set of items.
find( fn, ignoreFiltersfalse )
: Object

Returns the first item in this Collection which elicits a truthy return value from the passed function.
findIndex( propertyName, value, ignoreFiltersfalse )
: Number

Return the index of the item with the specified key having the specified value.

By default, filtering is taken into account and this returns the index in the filtered dataset if present. To bypass this, pass the third parameter as true.

Only useful for indices configured with unique: true.
findItem( propertyName, value, ignoreFiltersfalse )
: Object/Set

Return the item with the specified key having the specified value.

By default, filtering is taken into account. To bypass this, pass the third parameter as true.

For indices configured with unique: false, a Set of items will be returned.
forEach( fn, ignoreFiltersfalse )

Executes the passed function for each item in this Collection, passing in the item, ths index, and the full item array.
get( id, ignoreFiltersfalse )
: Object

Returns the item with the passed id. By default, filtered are honoured, and if the item with the requested id is filtered out, nothing will be returned.

To return the item even if it has been filtered out, pass the second parameter as true.
getBy( propertyName, value, ignoreFiltersfalse )
: Object

Returns the item with passed property name equal to the passed value. By default, filtered are honoured, and if the item with the requested id is filtered out, nothing will be returned.

To return the item even if it has been filtered out, pass the third parameter as true.
includes( item, ignoreFiltersfalse )
: Boolean

Returns true if this Collection includes an item with the same id as the passed item.

By default, filtering is honoured, so if the item in question has been added, but is currently filtered out of visibility, false will be returned.

To query inclusion in the master, unfiltered dataset, pass the second parameter as true;
indexOf( item, ignoreFiltersfalse )
: Number

Returns the index of the item with the same id as the passed item.

By default, filtering is honoured, so if the item in question has been added, but is currently filtered out of visibility, -1 will be returned.

To find the index in the master, unfiltered dataset, pass the second parameter as true;
map( fn, ignoreFiltersfalse )
: Object[]

Extracts ths content of this Collection into an array based upon the passed value extraction function.
match( other )

This method ensures that every item in this Collection is replaced by the matched by id item in the other Collection.

By default, any items in this Collection which are not in the other Collection are removed.

If the second parameter is passed as false, then items which are not in the other Collection are not removed.

This can be used for example when updating a selected record Collection when a new Store or new store dataset arrives. The selected Collection must reference the latest versions of the selected record ids
move( items, beforeItem )
: Number

Moves an individual item, or a block of items to another location.
onItemMutation( item, wasSet )

internal

Call externally to update indices on item mutation (from Store)
rebuildIndices( )

internal

Called when the Collection is mutated and the indices have been flagged as invalid.

Rebuilds the indices object to allow lookup by keys.
reduce( fn, ignoreFiltersfalse, accumulator[] )
: *

Returns an accumulated value based on the passed function similar to Array.reduce.
remove( ...items )

Removes items from this Collection. Multiple items may be passed.

Any sorters sorters present are re-run.

Any filters filters present are re-run.

Note that if application functionality requires add and remove, the splice operation is preferred as it performs both operations in an atomic manner
removeFromIndices( item )

private

Remove an item from all indices
removeIndexEntry( item, propertyName, oldValue )

private

Remove an entry from an index, and if filtering is used also from the filtered index.
replaceValues( params )

internal

Replaces the internal values array with the passed values, or filteredValues array with the passed filteredValues. If filteredValues are not passed explicitly, but storage is filtered, decides internally values or filteredValues should be replaced by passed values.

Note that this takes ownership of the array, and the array must not be mutated by outside code.

This is an internal utility method, not designed for use by application code.

Triggers: change
splice( index0, toRemove, ...toAdd )

The core data set mutation method. Removes and adds at the same time. Analogous to the Arraysplice method.

Note that if items that are specified for removal are also in the toAdd array, then those items are not removed then appended. They remain in the same position relative to all remaining items.

Events

Events are triggered for certain actions in this class and can be listened for to react to those actions in your code

change

Fired when items are added, replace or removed
noChange

Fired when a splice operation is requested but the operation is a no-op and has caused no change to this Collection's dataset. The splice method's parameters are passed for reference.

Event handlers

Event handlers are callbacks called as a result of certain actions in this class

onChange

Called when items are added, replace or removed
onNoChange

Called when a splice operation is requested but the operation is a no-op and has caused no change to this Collection's dataset. The splice method's parameters are passed for reference.

Source path

Core/util/Collection.js

Inheritance tree1

Collection