Collection for lists, maps, hashsets and hashmaps inspired by Kotlin syntax.
Install the library via:
npm install --save @yobuligo/collections.typescript
There are 2 basic types, the general list and the hash set.
While the general list can have duplicated elements, the hash set can contain each element only once, as a hash is generated for each element, which is used as key to add the element to the list. That allows a much faster access especially for lists with many elements.
Each basic type has a specialization to handle either any type of data or map specific data (key value pairs). Therefore special sub types were introduced.
Additionally these types are split into an immutable and a mutable variant. Finally there are the following list types and their creation functions:
type | immutable | mutable |
---|---|---|
list | listOf() | mutableListOf() |
map | mapOf() | mutableMapOf() |
hashSet | hashSetOf() | mutableHashSetOf() |
hashMap | hashMapOf() | mutableHashMapOf() |
Each list type has the same basic set of methods to request information about the list elements, like contains, distinct, filter, isEmpty, etc.
In addition, a list can have more specific methods depending on the list type. E.g. mutable lists have methods to add and remove elements, hash lists have no method to add an element at a given index and map lists can be converted to other map types.
A list can be created by giving the list type followed by the word Of. To initialize the list while creating it, it is possible to hand over elements.
const variant1 = listOf(1, 2, 3);
const variant2 = listOf(...["First", "Second", "Third"]);
const initialElements = [{ firstname: "Stacey" } , { firstname: "Jimmy" } ];
const variant3 = listOf(initialElements);
To initialize elements of map types, an instance of type Pair has to be passed into, which can be created by function pair().
const map = mapOf(pair(1, 2), pair(3, 4));
const hashMap = hashMapOf(pair("one", "two"), pair("three", "four"));
Basic functions are those functions, which are provided by every list.
Available for: All list types
Returns true if the passed in element is part of the list. Otherwise it returns false.
contains(element: T): boolean
Returns true if all passed in elements are part of the list. Otherwise it returns false.
containsAll(...elements: T[]): boolean
Returns true if the passed in element is not part of the list. Otherwise it returns false.
containsNot(element: T): boolean
Returns a newly created list, which contains all elements of the origin list except for duplicates.
Duplicates are identified by comparing the line type T, no matter if it is a scalar type or a reference type.
distinct(): IList<T>
Returns a newly created list, which contains all elements of the origin list except for duplicates.
Duplicates are identified by comparing the property key K of the line type T, which is returned by the selector.
distinctBy<K extends keyof T>(selector: () => K): IList<T>
Returns the element at position index or throws a NoSuchElementException if index is not assigned.
elementAt(index: number): T
Returns the element at position index or returns undefined if index is not assigned.
elementAtOrNull(index: number): T | undefined
Returns a newly created list, which contains all elements who match the required conditions. The conditions have to be evaluated by function predicate.
For a matching element the function predicate returns true otherwise false. If no element matches the filter an empty list is returned.
filter(predicate: (element: T) => boolean): IList<T>
Returns the first element, which matches the required conditions. The conditions have to be evaluated by function predicate.
For a matching element the function predicate returns true otherwise false. If no element matches the filter undefined is returned.
find(predicate: (element: T) => boolean): T | undefined
Returns the first element of that list or throws a NoSuchElementException if the list is empty.
first(): T
Returns the first element of that list or returns undefined if the list is empty.
firstOrNull(): T | undefined
Iterates over all elements of that list and calls the function block for each element.
If block returns a value the iteration is stopped and the value will be returned.
forEach<R>(block: (element: T, index: number) => R | undefined): R | undefined
Returns the index of the given element or -1 if the element is not part of the list.
indexOf(element: T): number
Returns true if the list is empty or false if the list contains at least one element.
isEmpty(): boolean
Returns true if the list contains at least one element or false if the list is empty.
isNotEmpty(): boolean
Returns the last element of that list or throws a NoSuchElementException if the list is empty.
last(): T
Returns the last element of that list or returns undefined if the list is empty.
lastOrNull(): T | undefined
Returns the index of the last element in that list.
readonly lastIndex: number
Returns a newly created list, which contains elements of type R, which were mapped by calling function block for each list element and returning an element of type R instead.
If the list is empty an empty list is returned.
map<R>(block: (element: T) => R): IList<R>
Returns a random element from the list or throws a NoSuchElementException if the list is empty.
random(): T
Returns a random element from the list or returns undefined if the list is empty.
randomOrNull(): T | undefined
Returns a newly created list, which contains all elements in a reversed order.
If the list is empty an empty list is returned.
reversed(): IList<T>
Returns the number of elements in that list.
readonly size: number
Returns a newly created, ascendingly sorted list. The sort criteria, which must be a key K of the line type T, can be provided via function selector.
If no sort criteria was specified the list element itself is used as sort criteria.
sortedBy<K extends keyof T>(selector?: () => K): IList<T>
Returns a newly created, descendingly sorted list. The sort criteria, which must be a key K of the line type T, can be provided via function selector.
If no sort criteria was specified the list element itself is used as sort criteria.
sortedByDescending<K extends keyof T>(selector?: () => K): IList<T>
Returns an array, which contains all elements of that list.
toArray(): T[]
Returns a hash set, which contains all elements, except for duplicates, of that list.
toHashSet(): IHashSet<T>
Returns a list, which contains all elements of that list.
toList(): IList<T>
Returns a mutable hash set, which contains all elements, except for duplicates, of that list.
toMutableHashSet(): IMutableHashSet<T>
Returns a mutable list, which contains all elements of that list.
toMutableList(): IMutableList<T>
Basic mutable functions are those functions, which are provided by every mutable list.
Available for: mutableListOf(), mutableMapOf(), mutableHashSetOf(), mutableHashMapOf()
Removes all instances of the given element from the list and returns true. Returns false if the given element is not part of the list.
remove(element: T): boolean
Removes the element at the given index from the list and returns true. Returns false if the element at index doesn't exist.
removeAt(index: number): boolean
Removes all elements from the list.
removeAll(): void
Removes the first element from the list and returns true. Returns false if the list is empty.
removeFirst(): boolean
Removes the last element from the list and returns true. Returns false if the list is empty.
removeLast(): boolean
Mutable list functions are specific for the general list which can have duplicates.
Available for: mutableListOf(), mutableMapOf()
Adds the given element to the list and returns true. Returns false if the element couldn't be added.
add(element: T): boolean
Adds the given element at position index to the list and returns true. Returns false if the element couldn't be added.
Throws an IllegalArgumentException if the index is out of bounce (greater than lastIndex + 1).
add(element: T, index: number): boolean
Adds all given elements of IList to the current list and returns true. Returns false if at least one element couldn't be added.
addAll(elements: IList<T>): boolean
Adds all given elements of IList at position index to the current list and returns true. Returns false if at least one element couldn't be added.
Throws an IllegalArgumentException if the index is out of bounce (greater than lastIndex + 1).
addAll(elements: IList<T>, index: number): boolean
Adds all given elements of the array to the current list and returns true. Returns false if at least one element couldn't be added.
addArray(elements: T[]): boolean
Adds all given elements of the array at position index to the current list and returns true. Returns false if at least one element couldn't be added.
Throws an IllegalArgumentException if the index is out of bounce (greater than lastIndex + 1).
addArray(elements: T[], index: number): boolean
Mutable hash set functions are specific for hash lists which can't have duplicates.
Available for: mutableHashSetOf(), mutableHashMapOf()
Adds the given element to the list and returns true. Returns false if the element couldn't be added.
add(element: T): boolean
Adds all given elements of IList to the current list and returns true. Returns false if at least one element couldn't be added.
addAll(elements: IList<T>): boolean
Adds all given elements of the array to the current list and returns true. Returns false if at least one element couldn't be added.
addArray(elements: T[]): boolean
Map functions are specific for every map list type.
Available for: mapOf(), mutableMapOf(), hashMapOf(), mutableHashMapOf()
Returns a hash map, which contains all elements, except for duplicates, of that list.
toHashMap(): IHashMap<K, V>
Returns a map, which contains all elements of that list.
toMap(): IMap<K, V>;
Returns a mutable hash map, which contains all elements, except for duplicates, of that list.
toMutableHashMap(): IMutableHashMap<K, V>;
Returns a mutable map, which contains all elements of that list.
toMutableMap(): IMutableMap<K, V>;