The Collection Object provides a fluent, convenient wrapper for working with arrays of data. We'll use the collect function to create a new Collection instance from the array
As mentioned above, the collect function returns a new Collection instance for the given array. So, creating a collection is as simple as:
const arr = [1,2,3,4];
const collection = collect(arr);
or minified version
For the majority of this collection documentation, we'll discuss each method available on the Collection class. Remember, all of these methods may be chained to fluently manipulate the underlying array. Furthermore, almost every method returns a new Collection instance, allowing you to preserve the original copy of the collection when necessary:
The all method returns the underlying array represented by the collection:
const arr = [1,2,3,4]; const collection = collect(arr); const result = collection.all(); console.log(result); // [1, 2, 3, 4]
Alias for the avg method.
The avg method returns the average value of a given key:
const arr = [1,2,3,4,5,9,98,5]; const collection = collect(arr); let average = collection.avg; console.log(average); // 15.875
The chunk method breaks the collection into multiple, smaller collections of a given size:
const arr = [1, 2, 3, 4, 5, 6, 7]; const collection = collect(arr); const chunks = collection.chunk(4); const result = chunks.all(); console.log(result); // [[1, 2, 3, 4], [5, 6, 7]]
The collapse method collapses a collection of arrays into a single, flat collection:
const arr = [ [1, 2, 3], [4, 5, 6], [7, 8, 9], ]; const collection = collect(arr); const collapsed = collection.collapse(); const result = collapsed.all(); console.log(result); // [1, 2, 3, 4, 5, 6, 7, 8, 9]
The collect method returns a new Collection instance with the items currently in the collection:
const arr = [ [1, 2, 3], [4, 5, 6], [7, 8, 9], ]; const collection = collect(arr); const collapsed = collection.collapse(); const result = collapsed.all(); console.log(result); // [1, 2, 3, 4, 5, 6, 7, 8, 9]
The concat method appends the given array or collection's values onto the end of another collection:
const arr = ['John Doe']; const collection = collect(arr); const concated = collection.concat(['Jane Doe']).concat(['Jonny Doe']); const result = concated.all(); console.log(result); // ["John Doe", "Jane Doe", "Jonny Doe"]
You may also pass a callback to the contains to determine if all elements exists in the collection matching a given truth test:
const arr = [1, 2, 3, 4, 5]; const collection = collect(arr); let result = collection.contains((el,indx,arr) => { return el < 6; }); console.log(result); // true
you may pass a string or number to the contains method to determine whether the collection contains a given item value:
const arr = ['John Doe', 'Jane Doe']; const collection = collect(arr); let result = collection.contains('John Doe'); console.log(result); // true
In Addition, you may also pass an array to the contains method to determine whether the collection contains all the values that are given in the array:
const arr = ['John Doe', 'Jane Doe','2']; const collection = collect(arr); let result = collection.contains(['Jane Doe','2']); console.log(result); // true
You may also pass a callback to the containsLoose to determine if an element exists in the collection matching a given truth test:
const arr = [1, 2, 3, 4, 5]; const collection = collect(arr); let result = collection.containsLoose((el,indx,arr) => { return el >= 5; }); console.log(result); // true
you may pass a string or number to the containsLoose method to determine whether the collection contains a given item value (it will compare loosely):
const arr = ['John Doe', 'Jane Doe']; const collection = collect(arr); let result = collection.containsLoose('JOHN DOE'); console.log(result); // true
In Addition, you may also pass an array to the containsLoose method to determine whether the collection contains all the values that are given in the array, again (it will compare loosely):
const arr = ['John Doe', 'Jane Doe','2']; const collection = collect(arr); let result = collection.containsLoose(['JANE DOE',2]); console.log(result); // true
The count method returns the total number of items in the collection:
const arr = [1, 2, 3, 4]; const collection = collect(arr); let result = collection.count(); console.log(result); // 4
The countOccurrences method counts the occurrences of the given value in the collection.
const arr = [1, 2, 3,3, 4]; const collection = collect(arr); let result = collection.countOccurrences(3); console.log(result); // 2
The countOccurrences method uses "strict" comparisons when checking item values Use the countOccurrencesLoose method to filter using "loose" comparisons.
The diff method compares the collection against another collection or a plain javascript array based on its values. This method will return the values in the original collection that are not present in the given collection:
const arr = [1, 2, 3, 4, 5]; const collection = collect(arr); const diff = collection.diff([2, 4, 6, 8]); const result = diff.all(); console.log(result); // [1, 3, 5]
The diff method uses "strict" comparisons when checking item values Use the diffLoose method to filter using "loose" comparisons.
The duplicates method retrieves and returns duplicate values from the collection:
const arr = ['a', 'b', 'a', 'c', 'b']; const collection = collect(arr); const duplicates = collection.duplicates(); const result = duplicates.all(); console.log(result); // ["a", "b"]
This method has the same signature as the duplicates method; however, all values are compared using "loose" comparisons.
The each method iterates over the items in the collection and passes each item to a callback:
const arr = [1,2,3,4,5,6,7,8,9]; const collection = collect(arr); const multiply = collection.each((el,indx,arr) => { if(arr.length > 2 && arr[indx] === 1){ return el * 10; } return el; }); const result = multiply.all(); console.log(result); // [10, 2, 3, 4, 5, 6, 7, 8, 9]
The eachSpread method iterates over the collection's 2D array's items, passing each nested item value into the given callback:
const arr = [[1,2,3,4],[5,6,7,8]]; const collection = collect(arr); const multiply = collection.eachSpread((el,indexes,arr,arrInside) => { if(arr.length > 1 && arr[indexes[0]][indexes[1]] === 3 &&arrInside[indexes[1]] === 3){ return el * 10; } return el; }); const result = multiply.all(); console.log(result); // [1, 2, 30, 4, 5, 6, 7, 8]
The eacheachSpreadDeep method iterates over the collection's multidimensional array's items, passing each nested item value into the given callback (You will not have access to the array indexes):
const arr = [1,2,[3,4,[5,6,[7,[[8,9]]]]]]; const collection = collect(arr); const multiply = collection. eachSpreadDeep((el) => { return el * 10; }); const result = multiply.all(); console.log(result); // [10, 20, 30, 40, 50, 60, 70, 80, 90]
The every method works precisely like built in array method 'every', except it will work on Collection instance. The every method may be used to verify that all elements of a collection pass a given truth test:
const isBelowThreshold = (currentValue) => currentValue < 40; const arr = [1, 30, 39, 29, 10, 13]; const collection = collect(arr); let result = collection.every(isBelowThreshold) console.log(result); // true
If the collection is empty, the every method will return true:
The except method returns all items in the collection except for those within the given collection or a plain javascript array.
const arr = ['aa','bb','cc',1,2,3]; const collection = collect(arr); const collection2 = collect(['aa','bb']); const except = collection.except(collection2); const result = except.all(); console.log(result); // ["cc", 1, 2, 3]
The except method uses "strict" comparisons when checking item values Use the exceptLoose method to filter using "loose" comparisons.
The filter method works precisely like built in array method 'filter', except it will work on Collection instance and returns a collection instance. The filter method filters the collection using the given callback, keeping only those items that pass a given truth test:
const arr = ['aa','bb','cc',1,2,3]; const collection = collect(arr); const filter = collection.filter(el => { return el > 0; }); const result = filter.all() console.log(result); // [1, 2, 3]