ts-fluent-iterators • Docs
ts-fluent-iterators / FluentIterator
Iterator with a Fluent interface.
• A
The type of elements being iterated.
Iterator<A>Iterable<A>
new FluentIterator<
A>(iter):FluentIterator<A>
Creates a FluentIterator by wrapping an Iterator
• iter: Iterator<A, any, undefined>
The Iterator being wrapped into a FluentIterator
const iterator = new FluentIterator([1, 2, 3][Symbol.iterator]());[iterator]():
Iterator<A,any,undefined>
Used to make this FluentIterator being seen as an
Iterable<A>. This allows them to be used in APIs expecting an
Iterable<A>
Iterator<A, any, undefined>
Iterable.[iterator]
all(
predicate):boolean
Returns true if the predicate argument evalatues to true for all items of this FluentIterator, false otherwsie.
• predicate: Predicate<A>
The predicate being evaluated
boolean
iterator([1, 2]).all(x => x > 0); // true
iterator([1, 2]).all(x => x >= 2); // false
FluentIterator.empty().all(_ => false); // true;append(
items):FluentIterator<A>
Returns a new FluentIterator that is the result of appending its argument to this FluentIterator
• items: Iterator<A, any, undefined> | Iterable<A>
An Iterator or Iterable whose items are appended to this FluentIterator.
iterator([1, 2, 3]).append([4, 5, 6]);
// yield 1, 2, 3, 4, 5, 6apply<
B>(mapper):B
Returns the resulf of applying the Mapper to the wrapped iterator. This method allows to use an Iterator function in a fluent way.
• B = A
• mapper: Mapper<Iterator<A, any, undefined>, B>
B
function sumOfIterator(Iterator<number>: iter) {
let sum = 0;
for (;;) {
const item = iter.next();
if (item.done) return sum;
sum += item.value;
}
}
iterator([1,2,3]).apply(sumOfiterator);
// returns 6collect():
A[]
Collects items into an array.
A[]
an array consisting of the elements of this FluentIterator
const iter = iterator([1, 2, 3]);
const data = iter.collect();
// data is [1,2,3]collectTo<
B>(collector):B
Collects items from the FluentIterator into a Collector.
• B
The result type of the Collector.
• collector: Collector<A, B>
The Collector into which to collect the items
B
The result of the collector
const collector = new ArrayCollector<string>();
const iter = iterator([1, 2, 3]);
const data = iter.collectTo(collector);
// data is [1,2,3]collectToMap<
K>(mapper,collisionHandler?):Map<K,A>
Collects items into a Map by mapping values into keys.
• K
The type of the keys of the Map
• mapper: Mapper<A, K>
Maps the values into keys
• collisionHandler?: CollisionHandler<K, A>
Specifies how to handle the collision. Default is to ignore collision.
Map<K, A>
a Map whose keys are the result of applying the mapper to the values of this FluentIterator and the values are iterated items.
const iter = iterator('foo', 'bar', 'foobar');
const data = iter.collectToMap(s => s.length);
// data is Map {3 => "foo", 6 => "foobar"}collectToMap2<
K,V>(mapper,collisionHandler?):Map<K,V>
Collects items into a Map by mapping values into keys and new value
• K
The type of the keys of the Map
• V
The type of the values of the Map
• mapper: Mapper<A, [K, V]>
Maps the values into [key, values] pairs
• collisionHandler?: CollisionHandler<K, V>
Specifies how to handle the collision. Default is to ignore collision.
Map<K, V>
a Map whose entries are the result of applying the mapper to the values of this FluentIterator.
const iter = iterator('foo', 'bar', 'foobar');
const data = iter.collectToMap2(s => [s, s.length]);
// data is Map { "foo" => 3, "bar" => 3, "foobar" => 6 }collectToObject<
V>(mapper,collisionHandler?):Record<string,V>
Collects items into a Record by mapping values into keys and new value
• V
The type of the values of the Map
• mapper: Mapper<A, [string, V]>
Maps the values into [key, values] pairs
• collisionHandler?: CollisionHandler<string, V>
Specifies how to handle the collision. Default is to ignore collision.
Record<string, V>
a Record whose entries are the result of applying the mapper to the values of this FluentIterator.
const iter = iterator('foo', 'bar', 'foobar');
const data = iter.collectToObject(s => [s, s.length]);
// data is { foo: 3, bar: 3, foobar: 6 }collectToSet():
Set<A>
Collects items into a Set.
Set<A>
a Set consisting of the elements of this FluentIterator
const iter = iterator([1, 2, 3, 1, 2, 3]);
const data = iter.collectToSet();
// data is Set { 1,2,3 }concat(...
iterables):FluentIterator<A>
Returns a new FluentIterator that is the result of apepending all its argument to this FluentIterator
• ...iterables: (Iterator<A, any, undefined> | Iterable<A>)[]
An Array of IteratororIterable` whose items are appended to this FluentIterator.
iterator([1, 2, 3]).concat([4, 5, 6], [7, 8, 9]);
// yield 1, 2 ,3, 4, 5, 6, 7, 8, 9contains(
predicate):boolean
Returns true if this FluentIterator yields an element for which the Predicate evaluates to true.
• predicate: Predicate<A>
The predicate to evaluate.
boolean
true if this FluentIterator yields an element for which the Predicate evaluates to true, false otherwise.
count():
number
Returns the number of items in this FluentIterator.
number
iterator([1, 2]).count(); // 2
FluentIterator.empty().count();
0;distinct<
K>(mapper?):FluentIterator<A>
Returns a new FluentIterator consisting of distinct elements from this iterator.
• K = A
• mapper?: Mapper<A, K>
Used to determine distinctness of elements. Default to identity
iterator([1,2,2,3,1,4]).distinct();
yields 1,2,3,4
iterator ([1,2,2,3,1,4], x => x %2).distinct();
yields 1,2enumerate(
start):FluentIterator<[A,number]>
Returns a new FluentIterator that yields pairs of elements consisting of the elements yielded by this @{link FluentIterator} and their index in the iteration.
• start: number= 0
The starting index
FluentIterator<[A, number]>
const iter = iterator(['a', 'b', 'c']);
const enumerated = iter.enumerate(10);
// enumerated will yield ["a", 10], ["b", 11], ["c", 12]filter(
predicate):FluentIterator<A>
Returns a new FluentIterator consisting of elements for which the predicate evaluates to true.
• predicate: Predicate<A>
the predicate on which the evaluate the items.
a new FluentIterator consisting of elements of this FluentIterator for which the predicate evaluates to true.
iterator([1, 8, 2, 3, 4, 6]).filter(x => x % 2 === 1);
// yields 1, 2filterMap<
B>(mapper):FluentIterator<B>
Returns a new FluentIterator consisting of applying the Mapper to all elements of this FluentIterator and filtering those for which the Mapper returned null or undefined
• B
The type of the elements of the returned FluentIterator
• mapper: Mapper<A, undefined | null | B>
Transformation applied to elements of this FluentIterator
A new FluentIterator
iter.filterMap(mapper);is equivalent to
iter.map(mapper).removeNull();first():
undefined|A
Returns the first element of this FluentIterator or undefined if this FluentIterator is empty.
undefined | A
The first element of this FluentIterator or undefined.
fold<
B>(reducer,initialValue):B
Executes the reducer function on each element of this FluentIterator, in order, passing in the return value from the calculation on the preceding element. The final result of running the reducer across all elements of the array is a single value.
• B
• reducer: Reducer<A, B>
The reducer to be applied at each iteration.
• initialValue: B
The value of the accumulator to be used in the first call to reducer
B
B the type into which the elements are being folded to
If the FluentIterator is empty, initialValue is returned.
To compute the sum of elements of an array:
const sum = iterator([1,2,3])
.fold((acc, x) => acc + x, 0)
// sum = 6forEach(
mapper):void
Applies the mapper to each element of this FluentIterator
• mapper: Mapper<A, any>
the operation to be invoked on each element.
void
The results of invoking the mapper are ignored unless it throws.
iter.forEach(console.log);groupBy<
K>(mapper):Map<K,A[]>
Returns a Map where keys are the result of applying the parameter mapper to the elements of the
this FluentIterator and the values are Arrays of
the elements that are mapped to the same key.
• K
• mapper: Mapper<A, K>
The Mapper used to group items.
Map<K, A[]>
iterator([1, 2, 3]).groupBy(x => x % 2 === 0);
// Map { true => [2], false => [1, 3]}groupBy2<
K,V>(mapper):Map<K,V[]>
Returns a Map where entries are the result of applying the parameter mapper to the elements of the
this FluentIterator,
• K
• V
• mapper: Mapper<A, [K, V]>
The Mapper used to group items.
Map<K, V[]>
iterator([1,2,3]).groupBy2(x => [x % 2 === 0, 2 * x];
// Map { true => [4], false => [2, 6]}includes(
target):boolean
Returns true if this FluentIterator yields an element equals to target
• target: A
value to look for
boolean
true if this FluentIterator yields an element equals to target, false otherwise.
@
iter.includes(target);is equivalent to
iter.contains(x => x === target);join(
separator?,prefix?,suffix?):string
Joins items of this FluentIterator into a string.
• separator?: string
string used to delimite elements
• prefix?: string
string used to prefix the resulting string
• suffix?: string
string
iterator([1, 2, 3]).join(',', '[', ']');
// "[1,2,3]"The items are converted into a string using string-interpolation.
last():
undefined|A
Returns the last element of this FluentIterator
undefined | A
iterator([1, 2]).last();
// 2
FluentIterator.empty().last();
// undefinedmap<
B>(mapper):FluentIterator<B>
Returns a new FluentIterator consisting of applying the Mapper to all elements of this FluentIterator.
• B
The type of the elements of the returned FluentIterator
• mapper: Mapper<A, B>
Transformation applied to elements of this FluentIterator
A new FluentIterator
const iter = iterator(['foo','bar',foobar'])
iter.map(s => s.length)
// yields 3, 3, 6mapToPromise<
B>(mapper):PromiseIterator<B>
Returns a new PromiseIterator consisting of applying the Mapper to all elements of this FluentIterator.
• B
The type of the elements of the returned PromiseIterator
• mapper: Mapper<A, Promise<B>>
Transformation applied to elements of this FluentIterator
A new PromiseIterator
max(
comparator?):undefined|A
Returns the maximum element according to the argument comparator.
• comparator?: Comparator<A>
undefined | A
iterator([1, 2]).max();
// 2
iterator(['foo', 'foobar']).max((s1, s2) => s1.length - s2.length);
// 'foobar'
FluentIterator.empty().max(); // undefinedmin(
comparator?):undefined|A
Returns the minimum element according to the argument comparator.
• comparator?: Comparator<A>
The {link Comparator} used to order the elements.
undefined | A
iterator([1,2]).min();
// 1
iterator(['foo','foobar']).min(
(s1,s2) => s1.length - s2.length
);
// 'foo'
(
FluentIterator.empty().min();
// undefinedminmax(
comparator?):undefined|MinMax<A>
Returns the minimum and maximum element according to the argument comparator.
• comparator?: Comparator<A>
undefined | MinMax<A>
iterator([1, 2]).minmax();
// { min: 1, max: 2}
iterator(['foo', 'foobar']).minmax((s1, s2) => s1.length - s2.length);
// { min: 'foo', max: 'foobar' }
FluentIterator.empty().minmax();
// undefinednext():
IteratorResult<A,any>
Used to make this FluentIterator being seen as an
Iterator<A>. This allows FluentIterator objects to be
used in APIs expecting an Iterator<A>
IteratorResult<A, any>
Iterator.next
partition(
size):FluentIterator<A[]>
Returns a new FluentIterator consisting of
partitions (arrays) of at most size elements.
• size: number
The size of the partitions.
FluentIterator<A[]>
iterator([1, 2, 3, 4, 5]).partition(2);
// yields [1, 2], [3, 4], [5]The last partition may contain less than size elements but is
never empty.
prepend(
items):FluentIterator<A>
Returns a new FluentIterator that is the result of prepending its argument to this FluentIterator
• items: Iterator<A, any, undefined> | Iterable<A>
An Iterator or Iterable whose items are prepended to this FluentIterator.
iterator([1, 2, 3]).prepend([4, 5, 6]);
// yield 4, 5, 6, 1, 2, 3reduce(
reducer,initialValue?):undefined|A
Special case of FluentIterator.fold where items being iteraded on and the accumulator are of the same type.
• reducer: Reducer<A, A>
The reducer to be applied at each iteration.
• initialValue?: A
The value of the accumulator to be used in the first call to reducer. If omitted, the first element of this FluentIterator is used.
undefined | A
If the FluentIterator is empty, initialValue is returned.
To compute the sum of elements of an array:
const sum = iterator([1,2,3])
.reduce((acc, x) => acc + x)
// sum = 6removeNull():
FluentIterator<A>
Returns a new FluentIterator consisting of elements of this FluentIterator that are not null nor undefined
a new FluentIterator where all the null or undefined elements are removed.
skip(
n):FluentIterator<A>
Returns a FluentIterator skipping the first n elements of this FluentIterator and then yielding the subsequent ones.
• n: number
The number of elements to skip
a FluentIterator skpping the first n elements of this FluentIterator.
If there are less than n elements in this FluentIterator, then an empty FluentIterator is returned.
skipWhile(
predicate):FluentIterator<A>
Returns a new FluentIterator that skips elements of this
FluentIterator until the predicate
evaluates to true and yields the subsequent ones.
• predicate: Predicate<A>
The predicate being evaluated
iterator([1, 2, 3]).skipWhile(x => x < 2); // yields 2, 3
iterator([1, 2, 3]).skipWhile(x => x > 2); // yields 1, 2, 3some(
predicate):boolean
Returns true if the predicate argument evalatues to true for some items of this FluentIterator, false otherwsie.
• predicate: Predicate<A>
The predicate being evaluated
boolean
iterator([1, 2]).some(x => x > 1); // true
iterator([1, 2]).some(x => x > 2); // false
FluentIterator.empty().some(_ => true); // false;take(
n):FluentIterator<A>
Returns a FluentIterator yielding the first n elements of this FluentIterator.
• n: number
The number of elements to take
a FluentIterator yielding the first n elements of this FluentIterator.
If there are less than n elements in this FluentIterator, then only the available elements will be yielded.
takeWhile(
predicate):FluentIterator<A>
Returns a new FluentIterator that yields elements of this FluentIterator while the predicate evaluates to true.
• predicate: Predicate<A>
The predicate being evaluated
iterator([1, 2, 3]).takeWhile(x => x < 2); // yields 1
iterator([1, 2, 3]).takeWhile(x => x > 2); // empty iteratortally():
Map<A,number>
Returns a Map of the count of the occurences of each items of
this FluentIterator,
Map<A, number>
iterator([foo','bar','foo').tally();
// Map { 'foo' => 2, bar => 1 }tap(
mapper):FluentIterator<A>
Returns a new FluentIterator that yields the same elements as this FluentIterator and executes the mapper on each element.
• mapper: Mapper<A, any>
the operation to be invoked on each element.
This can be useful to see intermediate steps of complex FluentIterator. The results of invoking the mapper are ignored unless it throwws.
const iter = iterator([1, 2, 3]);
iter
.tap(x => console.log(`before filter ${x}`))
.filter(x => x % 2 === 0)
.tap(x => console.log(`after filter: ${x}`))
.collect();
// ouputs:
// before filter 1
// before filter 2
// after filter: 2
// before filter 3
// result : [ 2 ]toAsync():
AsyncFluentIterator<A>
Converts this FluentIterator into an AsyncFluentIterator
An AsyncFluentIterator yielding the same elements as this FluentIterator
toPromise():
PromiseIterator<Awaited<A>>
Converts this FluentIterator into a PromiseIterator
PromiseIterator<Awaited<A>>
A PromiseIterator yielding the same elements as this FluentIterator
transform<
B>(mapper):FluentIterator<B>
Returns a new FluentIterator that is the result of transforming this FluentIterator. This method allows to use a an Iterartor transformation in a fluent way.
• B
• mapper: Mapper<Iterator<A, any, undefined>, Iterator<B, any, undefined>>
The mapper to transform the iterator.
function *doubleIterator(Iterator<number>: iter) {
for (;;) {
const item = iter.next();
if (item.done) break;
yield item.value * 2;
}
}
iterator([1,2,3]).transform(doubleIterator).collect()
// [2, 4, 6]zip<
B>(other):FluentIterator<[A,B]>
Returns a new FluentIterator that yields pairs of elements yielded by each Iterators which are navigated in parallel. The length of the new FluentIterator is equal to the length the shorter iterator.
• B
The type of elements of the other iterator.
• other: Iterator<B, any, undefined> | Iterable<B>
The iterator that is combined with this one.
FluentIterator<[A, B]>
const iter = iterator([1, 2, 3]);
const zipped = iter.zip(['a', 'b']);
// zipped will yield [1,"a"], [2,"b"]
staticempty<A>():FluentIterator<A>
Creates an empty FluentIterator. The returned iterator will not yield any element.
• A = never
the type of elements of the FluentIterator
An empty FluentIterator
staticfrom<A>(generator):FluentIterator<A>
Creates a FluentIterator from an IteratorGenerator.
• A
the type of elements of the FluentIterator
• generator: IteratorGenerator<A>
Used to generate an Iterator that will be wrapped into a FluentIterator
A new FluentIterator
const iter = FluentIterator.from([1, 2, 3]);