The type of the collection keys.
The type of the collection values.
Creates a new instance of the Collection class.
Items to be added to the collection.
If items is not one of the accepted types.
Private itemsThe items contained in the collection
The Symbol.iterator method returns an iterator object for the items in the current object.
This method is used to make the object iterable, allowing it to be used in the for…of loop.
An iterator object that can be used to iterate through the items in the object.
const collection = new Collection([1, 2, 3]);
for (const [key, value] of collection) {
console.log(key, value);
}
// expected output: 0 1
// expected output: 1 2
// expected output: 2 3
Returns all the elements in the collection.
If the collection is an array, an array of values, otherwise the map itself.
const collection = new Collection([1, 2, 3]);
collection.all(); // [1, 2, 3]
// or
const collection = new Collection({a: 1, b: 2, c: 3});
collection.all(); // Map { 'a' => 1, 'b' => 2, 'c' => 3 }
Calculates the average value of the elements in the collection.
Optional callback: string | ((item) => unknown)An optional callback function or property name to retrieve a value from each element. If a callback function is provided, it will be called with each element in the collection and should return the value to use for averaging. If a string is provided, it will be treated as the property name to retrieve the value from each element.
NaN will be returned.const collection = new Collection([1, 2, 3]);
collection.avg(); // 2
// or
const collection = new Collection([{a: 1}, {a: 2}, {a: 3}]);
collection.avg('a'); // 2
// or
const collection = new Collection([{a: 1}, {a: 2}, {a: 3}]);
collection.avg((item) => item.a); // 2
// or
const collection = new Collection([{a: 1}, {a: 2}, {a: 3}]);
collection.avg((item) => item.b); // NaN
Collapses the values of the collection into a new collection.
A new Collection object containing the collapsed values.
const collection = new Collection([[1, 2], [3, 4], [5, 6]]);
collection.collapse(); // Collection { 0 => 1, 1 => 2, 2 => 3, 3 => 4, 4 => 5, 5 => 6 }
Creates a new collection containing all the elements of the current collection.
A new collection with all the elements of the current collection.
const collection = new Collection([1, 2, 3]);
collection.collect(); // Collection { 0 => 1, 1 => 2, 2 => 3 }
Combines an array or Collection (as keys) with the items (as values) of the current Collection.
The type of the values in the given array or Collection.
The array or Collection with the keys to be combined.
A new Collection with combined items (keys from values, values from existing items).
const collection = new Collection([1, 2, 3]);
collection.combine([4, 5, 6]); // Collection { 1 => 4, 2 => 5, 3 => 6 }
Concatenates the items from the given source collection to the current collection.
The source collection to concatenate.
A new collection with the concatenated items.
const collection = new Collection([1, 2, 3]);
collection.concat([4, 5, 6]); // Collection { 0 => 1, 1 => 2, 2 => 3, 3 => 4, 4 => 5, 5 => 6 }
Checks if the map contains a specific key, value, or a custom function.
The key, value, or custom function to search for.
Optional operator: anyOptional. The operator to be used for custom function operations.
Optional value: anyOptional. The value to be used for comparison operations.
const collection = new Collection([1, 2, 3]);
collection.contains(2); // true
// or
const collection = new Collection([1, 2, 3]);
collection.contains((item) => item === 2); // true
// or
const collection = new Collection([1, 2, 3]);
collection.contains(2, '===', 2); // true
Checks if the given array contains exactly one item.
True if the array contains exactly one item, false otherwise.
const collection = new Collection([1]);
collection.containsOneItem(); // true
// or
const collection = new Collection([1, 2]);
collection.containsOneItem(); // false
Determine if an item exists, using strict comparison.
A function that returns a boolean type, a TValue, or an array key
A TValue or null
boolean
const collection = new Collection([1, 2, 3]);
collection.containsStrict(2); // true
// or
const collection = new Collection([1, 2, 3]);
collection.containsStrict((item) => item === 2); // true
// or
const collection = new Collection([1, 2, 3]);
collection.containsStrict(2, 2); // true
Calculates the difference between the current collection and the given collection.
The collection to compare with the current collection.
A new collection containing the items that are present in the current collection but not in the given collection.
const collection = new Collection([1, 2, 3]);
collection.diff([1, 2, 4]); // Collection { 2 => 3 }
Calculates the difference between this collection and the given collection based on key-value associations. Returns a new Collection object that contains all key-value pairs from this collection, which are not present in the given collection.
The collection to compare against this collection.
A new Collection object containing the key-value pairs that are in this collection but not in the given collection.
const collection = new Collection({a: 1, b: 2, c: 3});
collection.diffAssoc({a: 1, b: 2, c: 4, d: 5}); // Collection { 'c' => 3 }
Returns a new Collection that contains only the key-value pairs whose keys are not present in the provided items.
The items to compare keys against.
A new Collection instance that contains key-value pairs whose keys are not present in the provided items.
const collection = new Collection({a: 1, b: 2, c: 3});
collection.diffKeys({a: 1, c: 4, d: 5}); // Collection { 'b' => 2 }
Checks if the item does not exist in the collection.
The item to check for existence.
Optional operator: anyOptional operator parameter.
Optional value: anyOptional value parameter.
Returns true if the item does not exist in the collection, otherwise returns false.
const collection = new Collection([1, 2, 3]);
collection.doesntContain(2); // false
// or
const collection = new Collection([1, 2, 3]);
collection.doesntContain((item) => item === 2); // false
// or
const collection = new Collection([1, 2, 3]);
collection.doesntContain(2, '===', 2); // false
Execute a callback over each item.
The callback function to be applied to each element. The callback should accept two parameters: item and key. The item parameter represents the value of the current element. The key parameter represents the key of the current element.
Returns the collection itself.
const collection = new Collection([1, 2, 3]);
collection.each((item, key) => console.log(item, key)); // 1 0, 2 1, 3 2
Get the entries array of the collection items in [key, value] format.
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/entries
const collection = new Collection([1, 2, 3]);
collection.entries(); // [ [ 0, 1 ], [ 1, 2 ], [ 2, 3 ] ]
Checks whether every element in the map satisfies the given condition.
The function used to test each element in the map.
Optional operator: unknownOptional operator argument.
Optional value: unknownOptional value argument.
true if every element satisfies the condition, otherwise false.
const collection = new Collection([1, 2, 3]);
collection.every((item) => item > 0); // true
// or
const collection = new Collection([1, 2, 3]);
collection.every((item) => item > 1); // false
// or
const collection = new Collection([1, 2, 3]);
collection.every((item) => item > 1, '===', 2); // false
Filters the entries of the collection based on the provided callback function. It creates and returns a new Collection instance containing the filtered entries.
Optional callback: ((value, key) => boolean)The callback function used to filter each entry. The function takes two parameters: the value and key of each entry. It should return true to keep the entry or false to remove it.
A new Collection instance with the filtered entries.
const collection = new Collection([1, 2, 3]);
collection.filter((item) => item > 1); // Collection { 1 => 2, 2 => 3 }
Retrieves the first value that matches the provided callback function. If no callback function is provided, returns the first value in the collection. If no values are in the collection, returns the default value.
The type of the default value.
Optional callback: ((value, key) => boolean)The callback function used to match the values. The function should accept two arguments: the current value and the current key. It should return a boolean value indicating whether the value matches the criterion.
Optional defaultValue: D | (() => D)The default value to return if no match is found. If a function is provided, it will be executed to generate the default value.
The first value in the collection that matches the callback function, or the default value if no match is found.
const collection = new Collection({key1: 'value', key2: 'value2'});
// Example with callback function
const result1 = collection.first((value, key) => key === "key2");
console.log(result1); // Output: "value2"
// Example without callback function
const result2 = collection.first();
console.log(result2); // Output: "value1"
// Example with default value
const result3 = collection.first('key3', "default");
console.log(result3); // Output: "default"
Flattens the collection to a one-dimensional array.
The depth to which the collection should be flattened. Defaults to Infinity.
A new Collection object with the flattened array.
const collection = new Collection([[1, 2], [3, 4], [5, 6]]);
collection.flatten(); // Collection { 0 => 1, 1 => 2, 2 => 3, 3 => 4, 4 => 5, 5 => 6 }
Retrieves the value associated with the specified key from the collection. If the key is found, the corresponding value is returned. If the key is not found, the fallback value is returned.
The type of the fallback value.
The key to retrieve the value for.
Optional fallback: DThe fallback value to return if the key is not found. Default is undefined.
The value associated with the key, or the fallback value if the key is not found.
const collection = new Collection([1, 2, 3]);
collection.get(2); // 3
// or
const collection = new Collection({a: 1, b: 2, c: 3});
collection.get('b'); // 2
// or
const collection = new Collection([1, 2, 3]);
collection.get(4, 'default'); // 'default'
Protected getProtected Returns a Map object containing items suitable for iteration.
The input collection of items.
A Map object containing the objectable items.
Checks if all the specified keys are present in the items map.
Rest ...keys: K[]The keys to check for presence in the items map.
Returns true if all the keys are present, false otherwise.
const collection = new Collection([1, 3, 5]);
collection.has(2); // true
// or
const collection = new Collection({a: 1, b: 2, c: 3});
collection.has('a'); // true
Protected isReturns a collection of keys for the current instance.
A collection of keys for the current instance.
const collection = new Collection({a: 1, b: 2, c: 3});
collection.keys(); // Collection { 0 => 'a', 1 => 'b', 2 => 'c' }
// or
const collection = new Collection([1, 2, 3]);
collection.keys(); // Collection { 0 => 0, 1 => 1, 2 => 2 }
Returns the last value in the collection that satisfies the provided callback function. If no callback function is provided, it returns the last value in the collection. If the collection is empty or the callback function doesn't find a match, it returns the defaultValue.
The type of the default value.
Optional callback: ((value, key) => boolean)The callback function used to determine if a value satisfies a condition. It should return true if the value satisfies the condition, otherwise false.
Optional defaultValue: DThe value to return if no match is found. Defaults to undefined.
The last value that satisfies the callback function, or the defaultValue if no match is found.
const collection = new Collection([1, 2, 3]);
collection.last((item) => item > 1); // 3
// or
const collection = new Collection([1, 2, 3]);
collection.last((item) => item > 3, 'default'); // 'default'
// or
const collection = new Collection([1, 2, 3]);
collection.last(); // 3
Maps each key-value pair in the Collection object to a new value using a provided callback function.
The type of the new values.
The function to be applied to each key-value pair. It should take two arguments: the value of the current key-value pair and the key of the current key-value pair.
A new Collection object with the same keys as the original object, but with the values transformed by the callback function.
const collection = new Collection([1, 2, 3]);
collection.map((item) => item * 2); // Collection { 0 => 2, 1 => 4, 2 => 6 }
// or
const collection = new Collection({a: 1, b: 2, c: 3});
collection.map((item) => item * 2); // Collection { 'a' => 2, 'b' => 4, 'c' => 6 }
Calculates the median value from an array of numbers.
Optional key: KOptional. The key to use for extracting values from objects in the array. If provided, the method will first use this.pluck(key) to extract values.
The median value. If the array is empty, returns NaN.
const collection = new Collection([1, 2, 3]);
collection.median(); // 2
// or
const collection = new Collection([{a: 1}, {a: 2}, {a: 3}]);
collection.median('a'); // 2
Returns an array containing the keys of the elements with the highest occurrence in the collection. If a key parameter is provided, mode returns the keys of the elements with the highest occurrence for that specific key.
Optional key: KOptional. The key parameter to filter the collection by.
An array containing the keys of the elements with the highest occurrence in the collection. Returns an empty array if the collection is empty.
const collection = new Collection([1, 2, 2, 3, 3, 3]);
collection.mode(); // [3]
// or
const collection = new Collection([{a: 1}, {a: 2}, {a: 2}, {a: 3}, {a: 3}, {a: 3}]);
collection.mode('a'); // [3]
Protected operatorProtected Returns a function that can be used as a filter in array methods like Array.filter().
The key or function to use for comparison.
Optional operator: stringThe comparison operator.
Optional value: anyThe value to compare against.
The filter function.
Retrieves values from a collection based on a given key.
The key to retrieve values for. Can be a string or number.
Optional key: string | numberOptional key to use for indexing the values. Can be a string or number.
A new Collection containing the retrieved values.
const collection = new Collection([{a: 1}, {a: 2}, {a: 3}]);
collection.pluck('a'); // Collection { 0 => 1, 1 => 2, 2 => 3 }
// or
const collection = new Collection([{a: 1, b: 1}, {a: 2, b: 2}, {a: 3, b: 3}]);
collection.pluck('a', 'b'); // Collection { 1 => 1, 2 => 2, 3 => 3 }
Adds one or more items to the collection.
Rest ...items: V[]The items to add to the collection.
The updated collection.
const collection = new Collection([1, 2, 3]);
collection.push(4, 5, 6); // Collection { 0 => 1, 1 => 2, 2 => 3, 3 => 4, 4 => 5, 5 => 6 }
Puts a new key-value pair into the map.
The key for the new entry. If the key is undefined it fallbacks to the push method.
The value for the new entry.
This collection instance, after the new entry is added.
const collection = new Collection({a: 1, b: 2, c: 3});
collection.put('d', 4); // Collection { 'a' => 1, 'b' => 2, 'c' => 3, 'd' => 4 }
// or
const collection = new Collection([1, 2, 3]);
collection.put(undefined, 4); // Collection { 0 => 1, 1 => 2, 2 => 3, 3 => 4 }
Applies a callback function to each item in the map and reduces them to a single value.
The type of the reduced value.
The function to execute on each item.
The initial value for the reduction.
The reduced value.
const collection = new Collection([1, 2, 3]);
collection.reduce((result, item) => result + item); // 6
// or
const collection = new Collection([1, 2, 3]);
collection.reduce((result, item) => result + item, 10); // 16
Reverses the order of the items in the collection.
A new collection with the items in reverse order.
const collection = new Collection([1, 2, 3]);
collection.reverse(); // Collection { 0 => 3, 1 => 2, 2 => 1 }
// or
const collection = new Collection({a: 1, b: 2, c: 3});
collection.reverse(); // Collection { 'c' => 3, 'b' => 2, 'a' => 1 }
Sorts the elements of the collection.
Optional callback: ((a, b) => number)(Optional) A callback function to determine the sort order. If provided, the function should accept two elements from the collection and return a negative number if the first element should be placed before the second element, 0 if the order should remain unchanged, or a positive number if the second element should be placed before the first element. If not provided, the default sorting order is used.
A new Collection with the elements sorted.
const collection = new Collection([3, 2, 1]);
collection.sort(); // Collection { 0 => 1, 1 => 2, 2 => 3 }
// or
const collection = new Collection([3, 2, 1]);
collection.sort((a, b) => b - a); // Collection { 0 => 3, 1 => 2, 2 => 1 }
// or
const collection = new Collection([{a: 3}, {a: 2}, {a: 1}]);
collection.sort((a, b) => a.a - b.a); // Collection { 0 => { a: 1 }, 1 => { a: 2 }, 2 => { a: 3 } }
// or
const collection = new Collection([{a: 3}, {a: 2}, {a: 1}]);
collection.sort(); // Collection { 0 => { a: 1 }, 1 => { a: 2 }, 2 => { a: 3 } }
Calculates the sum of the elements in the array.
Optional mapper: string | ((item) => number)Optional. A callback function or property name for mapping each value before performing the sum. If specified, the mapper function will be applied to each element in the array before summing. If a property name is provided, it will be used as a string accessor to retrieve the corresponding value from each element .
The sum of the elements in the array.
const collection = new Collection([1, 2, 3]);
collection.sum(); // 6
// or
const collection = new Collection([{a: 1}, {a: 2}, {a: 3}]);
collection.sum('a'); // 6
// or
const collection = new Collection([{a: 1}, {a: 2}, {a: 3}]);
collection.sum((item) => item.a); // 6
Converts the items of this object into a Map.
A new Map object containing the items of this object.
const collection = new Collection([1, 2, 3]);
collection.toMap(); // Map { 0 => 1, 1 => 2, 2 => 3 }
// or
const collection = new Collection({a: 1, b: 2, c: 3});
collection.toMap(); // Map { 'a' => 1, 'b' => 2, 'c' => 3 }
Converts the instance of the class to a plain object.
The plain object representation of the class.
const collection = new Collection([1, 2, 3]);
collection.toObject(); // { '0': 1, '1': 2, '2': 3 }
// or
const collection = new Collection({a: 1, b: 2, c: 3});
collection.toObject(); // { a: 1, b: 2, c: 3 }
Protected valueProtected Retrieves the value from an item using a callback function or a property path.
Optional callback: string | FunctionThe callback function or property path used to retrieve the value from the item.
The callback function to retrieve the value from
Returns a new Collection of values from the underlying items.
A new Collection of values.
const collection = new Collection([1, 2, 3]);
collection.values(); // Collection { 0 => 1, 1 => 2, 2 => 3 }
// or
const collection = new Collection({a: 1, b: 2, c: 3});
collection.values(); // Collection { 'a' => 1, 'b' => 2, 'c' => 3 }
Static makeCreate a new Collection instance.
The items to initialize the Collection with.
The newly created Collection instance.
const collection = Collection.make([1, 2, 3]); // Collection { 0 => 1, 1 => 2, 2 => 3 }
Static rangeCreate a collection with the given range.
The start of the range.
The end of the range.
The step of the range.
static
Collection.range(1, 5); // Collection { 0 => 1, 1 => 2, 2 => 3, 3 => 4, 4 => 5 }
// or
Collection.range(1, 5, 2); // Collection { 0 => 1, 1 => 3, 2 => 5 }
Generated using TypeDoc
A collection class for storing and manipulating items.