Collection

Extends Map

An extended JavaScript Map with additional utility methods.

To create a new Collection, initialise the class like below.

const Col = new QDB.Collection(Iterable?);

Take a look at the native JavaScript Map.

Method Index

Please note that this page includes the Map methods as well. Some of them are default, some are extended in the Colleciton class.

Properties

.size

The amount of key/value pairs this Collection contains.
Type - Number

Methods

.set(Key, Val)

Main interaction point of the Collection.

Parameter Type Description
Key Any The key of this entry.
Val Any The value of this pair.

Returns - Collection | This
Returns the Collection itself.

.get(Key)

Returns the value associated to the key, or undefined if there is none.

Parameter Type Description
Key Any The key of this entry.

Returns - Any | Undefined
Returns a the value or the pair, or a nil value.

.has(Key)

Returns a boolean asserting whether a value has been associated to the key in the Collection or not.

Parameter Type Description
Key Any The key of this entry.

Returns - Any | Undefined
Returns a the value or the pair, or a nil value.

.delete(Key)

Returns Collection if an element in the Collection object existed and has been removed, or false if the element does not exist. Col.has(Key) will return false afterwards.

Parameter Type Description
Key Any The key of this entry.

Returns - Collection | False
Returns a the value or the pair, or a nil value.

.clear(Key)

Removes all key-value pairs from the Collection object.

WARNING - Clears the Collection immediately.

Returns - Undefined

.first(Amount)

Obtains the first value(s) in this Collection.

Parameter Type Description
Amount Number Amount of values to obtain from the beginning.

Returns - Any | Array<Any>
A single value if no amount is provided, or an array of values, starting from the end if amount is negative.

.last(Amount)

Obtains the last value(s) in this Collection.

Parameter Type Description
Amount Number Amount of values to obtain from the end.

Returns - Any | Array<Any>
A single value if no amount is provided, or an array of values, starting from the beginning if amount is negative.

.random(Amount)

Obtains unique random value(s) from this Collection.

Parameter Type Description
Amount Number Amount of values to obtain randomly.

Returns - Any | Array<Any>
A single value if no amount is provided or an array of values.

.array()

Creates an ordered array of the values of this Collection and caches it internally. The array will only be reconstructed if an item is added added to or removed from the Collection, or if you change the length of the array itself. If you don't want this caching behaviour, use [...Col.values()] instead.

Returns - Array<Any>
Array of values in this Collection.

.keys()

Creates an ordered array of the keys in this Collection and caches it internally. The array will only be reconstructed if an item is added to or removed from the Collection, or if you change the length of the array itself. If you don't want this caching behaviour, use [...Col.keys()] instead.

Returns - Array<Any>
Array of keys in this Collection.

.values()

Creates an ordered array of the values of this Collection.

NOTE - For optimisation, use Col.array() instead.

Returns - Array<Any>
Array of values in this Collection.

.entries()

Returns a new Iterator object that contains an array of [Key, Val] for each element in the Collection object in insertion order.

Returns - Iterator<Array<Key, Val>>
Iterator containing arrays of key-value pairs.

.sweep(cfn, Self)

Removes entries that satisfy the provided filter function.

Parameter Type Description
cfn Function Function to test with (should return a boolean).
Self Any Value to use as this when executing functions.

Returns - Number
Number of removed entries.

.map(fn, Self)

Maps each item to another value.

Parameter Type Description
fn Function Function that produces an element of the new array.
Self Any Value to use as this when executing functions.

Returns - Array<Val>
Returns an array of the mapped values.

.partition(cfn, Self)

Partitions the Collection into two Collections, where the first Collection contains the items that passed and the second contains the items that failed.

Parameter Type Description
cfn Function Function to test with (should return a boolean).
Self Any Value to use as this when executing functions.

Returns - Array<Collection>
An array of partitioned Collections.

.reduce(fn, InitVal)

Applies a function to produce a single value.

Parameter Type Description
cfn Function Function used to reduce, taking four arguments; Accumulator, CurVal, CurKey, and this.
InitVal Any Starting value for the accumulator.

Returns - Any
The produced value of the function.

.merge(...Collections)

Combines this Collection with others into a new Collection. None of the source Collections will be modified.

Parameter Type Description
...Collections Collection(s) Collections to merge into one.

Returns - Collection
Returns a unique, merged Collection of the Collections.

.intersect(Second)

The intersect method returns a new Collection containing items where the keys are present in both original structures.

Parameter Type Description
Second Collection A Collection to filter against.

Returns - Collection
Second Collection with the filtered values of the first where they intersect.

.difference(Second)

The difference method returns a new structure containing items where the key is present in one of the original structures, but not the other.

Parameter Type Description
Second Collection A Collection to filter against.

Returns - Collection
Second Collection with unique items the first Collection does not have.

.backup(Second)

Creates an identical, shallow copy of this Collection.

Returns - Collection
A unique Collection with the items of the original.

.find(cfn, Self)

Searches for a single item where the given function returns a truthy value.

Parameter Type Description
cfn Function Function to test with (should return a boolean).
Self Any Value to use as this when executing functions.

Returns - Any
Returns value of the element found.

.filter(cfn, Self)

Identical to Array.filter();, but returns a Collection instead of an array.

Parameter Type Description
cfn Function Function to test with (should return a boolean).
Self Any Value to use as this when executing functions.

Returns - Collection
Returns the new filtered Collection.

.exists(cfn, Self)

Checks if there is an item that exists that passes a test.

Parameter Type Description
cfn Function Function to test with (should return a boolean).
Self Any Value to use as this when executing functions.

Returns - Boolean
Boolean to express whether at least one item has passed the test.

.every(cfn, Self)

Checks if all items pass the test.

Parameter Type Description
cfn Function Function to test with (should return a boolean).
Self Any Value to use as this when executing functions.

Returns - Boolean
Boolean to express if all items has passed the test.

.forEach(fn, Self)

Calls function once for each key-value pair present in the Collection, in insertion order. If a self parameter is provided to forEach, it will be used as the this value for each callback.

Parameter Type Description
fn Function Function with value, key and self.
Self Any Value to use as this when executing functions.

Returns - Undefined

.tap(fn)

Iterates on the Collection's items and returns the Collection itself. This function should rather be used instead of forEach.

Parameter Type Description
fn Function Function with the value and key per pair executed.

Returns - Collection
Returns this Collection.

.return(fn)

Asynchronised function which returns this Collection in a callback.

Parameter Type Description
fn Function Function with this Collection.

Returns - Collection
Returns this Collection.

.sort(cfn)

Sorts all the elements in the Collection and returns it.

NOTE - If omitted, the Collection is sorted according to each character's Unicode point value, according to the string conversion of each element.

Parameter Type Description
cfn Function Specifies a function that defines the sort order.

Returns - Collection
Returns a new Collection with sorted items.