Similar to what we know from C#, Dart or any other language which supports them,
we use Iterables to stream over collections.
Iterables are useful when you want to chain several operations on a collection such as
- filter
- filterNotNull
- group
- sort
- map
- mapNotNull
- take
- skip
- every
- none
- some
- etc ...
For example, lets consider a case. We need to work with a collection to filter the numbers greater than 20, map to
the string only the 3'rd value.
- Without the Iterable
const data = [1, 10, 20, 30, 40, 50, ...];
const filteredData = data.filter(x => x > 20);
const value = filteredData[3];
const mappedValue = value.toString();
// result "50"- Using the Iterable
const data = [1, 10, 20, 30, 40, 50, ...];
const mappedValue = asIterable(data)
.filter(x => x > 20)
.skip(2)
.map(x => x.toString())
.first()
// result "50"The Iterable code would be similar as
let skipped = 0;
for (let i = 0; i < data.length; i ) {
const element = data[i];
if (element > 20 && skipped < 2) return element.toString();
}
throw new NoElementError();Not only the difference stays that we have written it differently, but also how much data was processed.
On the example without using the Iterable
- All elements of the collection are visited and filtered
- The third element is retrieved
- The retrieved element is mapped to a string
Now, if the collection is really huge, this will take time to process.
While, using the Iterable, that is not necessarily as we know we do not need all the elements.
Because we call first() at the end, that means that the operation will stop as soon this condition is meet.
- Find from collection only the first value that is greater than
20 - Map the value to a string
npm i @xeinebiu/ts-iterableconst data = [1, 2, 3, 4, 5];
const iterable = asIterable(data);// without the Iterable
const filtered = data.filter(x => x < 4);
// with iterable
const filtered = asIterable(data)
.filter(x => x < 4)
.toList();
// result [1, 2, 3]Filter undefined|null values out
const data = [1, 2, null, 3, undefiend, 4];
const filtered = asIterable(data)
.filterNotNull();
// result [1, 2, 3, 4]Take specific amount of elements
// without iterable
const taken = data.slice(0, 3);
// with iterable
const taken = asIterable(data)
.take(3)
.toList();
// result [1, 2, 3]Return true if all elements match the predicate.
const result = asIterable(data)
.every(x => x.toString() !== "hello world");
// result trueReturn true if any of the elements match the predicate
const result = asIterable(data)
.some(x => x.toString() !== "1");
// result trueReturn true if all the elements do not match the predicate
const result = asIterable(data)
.none(x => x <= -1);
// result trueReturn the first element if available, otherwise throw NoElementError
const result = asIterable(data)
.filter(x => x > 4)
.first();
// result 5Return the first element if available, otherwise null.
const result = asIterable(data)
.filter(x => x > 100)
.firstOrNull();
// result nullMap the elements using a mapper
const result = asIterable(data)
.filter(x => x < 3)
.map(x => x.toString())
.toList();
// result ["1", "2"]Map the elements using the mapper and avoid inserting null|undefined values in the list
const data = [1, null, 2, undefined, 3];
const result = asIterable(data)
.filter(x => x < 3)
.mapNotNull(x => x?.toString())
.toList();
// result ["1", "2", "3"]Offset the elements cursor starting from index 0
const result = asIterable(data)
.skip(1)
.toList();
// result ["2", "3", "4", "5"]Take specific amount of elements
const result = asIterable(data)
.take(2)
.toList();
// result ["1", "2"]Sort all elements and return new [ExtendedIterable]
const sorted = asIterable(data)
.sort((a, b) => b - a)
.toList();
// result [5, 4, 3, 2, 1]Group all elements and return new [ExtendedIterable]
const data = [-9, -8, -7, -6, -5, -4, -3, -2, -1, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
const groupedData = asIterable(data)
.group(x => {
if (x < 0) return "negative";
return "positive";
})
.toList();
// result
// [
// ["negative", [-9, -8, -7, -6, -5, -4, -3, -2, -1]],
// ["positive", [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]]
// ];Convert the Iterable to a collection.
const list = asIterable(data)
.toList();
// result [1, 2, 3, 4, 5]