Iterable for Typescript
Similar to what we know from C#, Dart or any other language which supports them, we use Iterables to stream over collections.
Why using the Iterable?
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
Installation
npm i @xeinebiu/ts-iterable
Examples
Convert a list to iterable
const data = [1, 2, 3, 4, 5];
const iterable = asIterable(data);
Filter
// 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 Not Null
Filter undefined|null values out
const data = [1, 2, null, 3, undefiend, 4];
const filtered = asIterable(data)
.filterNotNull();
// result [1, 2, 3, 4]
Take
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]
Every
Return true if all elements match the predicate.
const result = asIterable(data)
.every(x => x.toString() !== "hello world");
// result true
Some
Return true if any of the elements match the predicate
const result = asIterable(data)
.some(x => x.toString() !== "1");
// result true
None
Return true if all the elements do not match the predicate
const result = asIterable(data)
.none(x => x <= -1);
// result true
First
Return the first element if available, otherwise throw NoElementError
const result = asIterable(data)
.filter(x => x > 4)
.first();
// result 5
First Or Null
Return the first element if available, otherwise null.
const result = asIterable(data)
.filter(x => x > 100)
.firstOrNull();
// result null
Map
Map the elements using a mapper
const result = asIterable(data)
.filter(x => x < 3)
.map(x => x.toString())
.toList();
// result ["1", "2"]
Map Not Null
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"]
Skip
Offset the elements cursor starting from index 0
const result = asIterable(data)
.skip(1)
.toList();
// result ["2", "3", "4", "5"]
Take
Take specific amount of elements
const result = asIterable(data)
.take(2)
.toList();
// result ["1", "2"]
Sort
Sort all elements and return new [ExtendedIterable]
const sorted = asIterable(data)
.sort((a, b) => b - a)
.toList();
// result [5, 4, 3, 2, 1]
Group
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]]
// ];
To List
Convert the Iterable to a collection.
const list = asIterable(data)
.toList();
// result [1, 2, 3, 4, 5]
4 May 3, 2022
14 Jan 3, 2023
11 Sep 10, 2022
11 Aug 15, 2022
36 Oct 5, 2022
48 Dec 29, 2022
18.7k Jan 4, 2023
2 Jun 3, 2022
315 Dec 29, 2022