iterator-helper

Provide helpers that polyfill all methods defined in iterator helpers proposal, both for Iterator and AsyncIterator, and even more.

Installation

Install it with npm/yarn/what you want.

1npm i iterator-helper

Getting started

You can wrap an iterable or an iterator with the exported iter (for standard iterables) and aiter (for async iterables) functions.

1import { iter, aiter } from 'iterator-helper';
2
3// It accepts both iterables and iterator, here it's an iterable
4const iterator = iter([1, 2, 3]);
5
6const mapped_cycle = iterator
7  .cycle() // Make the iterator cycle on end
8  .map(e => e * 2) // For each item, execute e => e * 2
9  .asIndexedPairs(); // For each item, return [iterator_index, item]
10
11for (const [index, element] of mapped_cycle) {
12  console.log(index, element);
13  // 0, 2
14  // 1, 4
15  // 2, 6
16  // 3, 2
17  // 4, 4
18  // 5, 6
19  // ...
20}

You can also extend two exported classes, HIterator and HAsyncIterator (those names are used to avoid conflicts with possible futures Iterator and AsyncIterator global objects), in order to make your classes iterables.

1import { HIterator } from 'iterator-helper';
2
3class RangeIterator extends HIterator {
4  constructor(start, stop = undefined, step = 1) {
5    super();
6    this.position = stop === undefined ? 0 : start;
7    this.stop = stop === undefined ? start : stop;
8    this.step = step;
9
10    if (stop < start) {
11      throw new Error('Stop cannot be inferior to start.');
12    }
13    if (step <= 0) {
14      throw new Error('Step must be superior to 0.');
15    }
16  }
17
18  next() {
19    if (this.position < this.stop) {
20      const current = this.position;
21      this.position += this.step;
22
23      return { value: current, done: false };
24    }
25
26    return { value: undefined, done: true };
27  }
28}
29
30const range = new RangeIterator(10).filter(e => e % 2 === 0);
31range.next(); // { value: 0, done: false };
32range.next(); // { value: 2, done: false };
33range.next(); // { value: 4, done: false };
34// ...

API

There are a few methods for each sync or async iterators. Here's the quick way, as TypeScript types with a description for each method:

1interface HIterator<T, TReturn = any, TNext = undefined> {
2  /** Map each value of iterator to another value via {callback}. */
3  map<R>(callback: (value: T) => R) : HIterator<R, TReturn, TNext>;
4
5  /** Each value is given through {callback}, return `true` if value is needed into returned iterator. */
6  filter(callback: (value: T) => boolean) : HIterator<T, TReturn, TNext>;
7
8  /** Create a new iterator that consume {limit} items, then stops. */
9  take(limit: number) : HIterator<T, TReturn, TNext>;
10
11  /** Create a new iterator that skip {limit} items from source iterator, then yield all values. */
12  drop(limit: number) : HIterator<T, TReturn, TNext>;
13
14  /** Get a pair [index, value] for each remaining value of iterable. */
15  asIndexedPairs() : HIterator<[number, T], TReturn, TNext>;
16
17  /** Like map, but you can return a new iterator that will be flattened. */
18  flatMap<R>(mapper: (value: T) => Iterator<R> | R) : HIterator<R, TReturn, TNext>;
19
20  /** Find a specific value that returns `true` in {callback}, and return it. Returns `undefined` otherwise. */
21  find(callback: (value: T) => boolean) : T | undefined;
22
23  /** Return `true` if each value of iterator validate {callback}. */
24  every(callback: (value: T) => boolean) : boolean;
25
26  /** Return `true` if one value of iterator validate {callback}. */
27  some(callback: (value: T) => boolean) : boolean;
28
29  /** Consume iterator and collapse values inside an array. */
30  toArray(maxCount?: number) : T[];
31
32  /** Accumulate each item inside **acc** for each value **value**. */
33  reduce<V>(reducer: (acc: V, value: T) => V, initialValue?: V) : V;
34
35  /** Iterate over each value of iterator by calling **callback** for each value. */
36  forEach(callback: (value: T) => any) : void;
37
38  /** End the iterator and return the number of remaining items. */
39  count() : number;
40
41  /** Join all the remaining elements of the iterator in a single string with glue {glue}. */
42  join(glue: string) : string;
43
44  /** Iterate through current iterator, then through the given iterators in the correct order. */
45  chain<I>(...iterables: IteratorOrIterable<I>[]) : HIterator<T | I>;
46
47  /** Iterate through multiple iterators together. */
48  zip<O>(...others: IteratorOrIterable<O>[]) : HIterator<(T | O)[]>;
49
50  /** Continue iterator until {callback} return a falsy value. */
51  takeWhile(callback: (value: T) => boolean) : HIterator<T>;
52
53  /** Skip elements until {callback} return a truthy value. */
54  dropWhile(callback: (value: T) => boolean) : HIterator<T>;
55
56  /** Continue iterator until `null` or `undefined` is encountered. */
57  fuse() : HIterator<T>;
58
59  /** Partition {true} elements to first array, {false} elements to second one. */
60  partition(callback: (value: T) => boolean) : [T[], T[]];
61
62  /** Find the iterator index of the first element that returns a truthy value, -1 otherwise. */
63  findIndex(callback: (value: T) => boolean) : number;
64
65  /** Only works if it is a number iterator. Returns the maximum of iterator. */
66  max() : number;
67
68  /** Only works if it is a number iterator. Returns the minimum of iterator. */
69  min() : number;
70
71  /** When iterator ends, go back to the first item then loop. Indefinitively. */
72  cycle() : HIterator<T>;
73
74  /** Group by objects by key according to returned key for each object. */
75  groupBy<K extends string | number | symbol>(callback: (value: T) => K) : { [Key in K]: T[] };
76
77  /** Index this iterator objects in a {Map} with key obtained through {keyGetter}. */
78  toIndexedItems<K>(keyGetter: (value: T) => K) : Map<K, T>;
79
80  /** Iterate over items present in both current collection and {otherItems} iterable. `O(n*m)` operation that will consume {otherItems} iterator/iterable! */
81  intersection<O>(otherItems: IteratorOrIterable<O>, isSameItemCallback: (value: T, other: O) => boolean = Object.is) : HIterator<T>;
82
83  /** Iterate over items present only in current collection, not in {otherItems} iterable. `O(n*m)` operation that will consume {otherItems} iterator/iterable! */
84  difference<O>(otherItems: IteratorOrIterable<O>, isSameItemCallback: (value: T, other: O) => boolean = Object.is) : HIterator<T>;
85
86  /** Iterate over items present only in current collection or only in {otherItems} iterable, but not in both. `O(n*m)` operation that will consume {otherItems} iterator/iterable! */
87  symmetricDifference<O>(otherItems: IteratorOrIterable<O>, isSameItemCallback: (value: T, other: O) => boolean = Object.is) : HIterator<T>;
88
89  /** Transform current sync iterator to an async one (wrap each new item into a resolved `Promise`) */
90  toAsyncIterator(): HAsyncIterator<T>;
91}
92
93interface HAsyncIterator<T, TReturn = any, TNext = undefined> {
94  /** Map each value of iterator to another value via {callback}. */
95  map<R>(callback: (value: T) => R | PromiseLike<R>) : HAsyncIterator<R, TReturn, TNext>;
96
97  /** Each value is given through {callback}, return `true` if value is needed into returned iterator. */
98  filter(callback: (value: T) => boolean | PromiseLike<boolean>) : HAsyncIterator<T, TReturn, TNext>;
99
100  /** Create a new iterator that consume {limit} items, then stops. */
101  take(limit: number) : HAsyncIterator<T, TReturn, TNext>;
102
103  /** Create a new iterator that skip {limit} items from source iterator, then yield all values. */
104  drop(limit: number) : HAsyncIterator<T, TReturn, TNext>;
105
106  /** Get a pair [index, value] for each remaining value of iterable. */
107  asIndexedPairs() : HAsyncIterator<[number, T], TReturn, TNext>;
108
109  /** Like map, but you can return a new iterator that will be flattened. */
110  flatMap<R>(mapper: (value: T) => AsyncIterator<R> | R) : HAsyncIterator<R, TReturn, TNext>;
111
112  /** Find a specific value that returns `true` in {callback}, and return it. Returns `undefined` otherwise. */
113  find(callback: (value: T) => boolean | PromiseLike<boolean>) : Promise<T | undefined>;
114
115  /** Return `true` if each value of iterator validate {callback}. */
116  every(callback: (value: T) => boolean | PromiseLike<boolean>) : Promise<boolean>;
117
118  /** Return `true` if one value of iterator validate {callback}. */
119  some(callback: (value: T) => boolean | PromiseLike<boolean>) : Promise<boolean>;
120
121  /** Consume iterator and collapse values inside an array. */
122  toArray(maxCount?: number) : Promise<T[]>;
123
124  /** Accumulate each item inside **acc** for each value **value**. */
125  reduce<V>(reducer: (acc: V, value: T) => V | PromiseLike<V>, initialValue?: V) : Promise<V>;
126
127  /** Iterate over each value of iterator by calling **callback** for each value. */
128  forEach(callback: (value: T) => any) : Promise<void>;
129
130  /** End the iterator and return the number of remaining items. */
131  count() : Promise<number>;
132
133  /** Join all the remaining elements of the iterator in a single string with glue {glue}. */
134  join(glue: string) : Promise<string>;
135
136  /** Iterate through current iterator, then through the given iterators in the correct order. */
137  chain<I>(...iterables: AsyncIteratorOrIterable<I>[]) : HAsyncIterator<T | I>;
138
139  /** Iterate through multiple iterators together. */
140  zip<O>(...others: AsyncIteratorOrIterable<O>[]) : HAsyncIterator<(T | O)[]>;
141
142  /** Continue iterator until {callback} return a falsy value. */
143  takeWhile(callback: (value: T) => boolean | PromiseLike<boolean>) : HAsyncIterator<T>;
144
145  /** Skip elements until {callback} return a truthy value. */
146  dropWhile(callback: (value: T) => boolean | PromiseLike<boolean>) : HAsyncIterator<T>;
147
148  /** Continue iterator until `null` or `undefined` is encountered. */
149  fuse() : HAsyncIterator<T>;
150
151  /** Partition {true} elements to first array, {false} elements to second one. */
152  partition(callback: (value: T) => boolean | PromiseLike<boolean>) : Promise<[T[], T[]]>;
153
154  /** Find the iterator index of the first element that returns a truthy value, -1 otherwise. */
155  findIndex(callback: (value: T) => boolean | PromiseLike<boolean>) : Promise<number>;
156
157  /** Only works if it. is a number iterator. Returns the maximum of iterator. */
158  max() : Promise<number>;
159
160  /** Only works if it. is a number iterator. Returns the minimum of iterator. */
161  min() : Promise<number>;
162
163  /** When iterator ends, go back to the first item then loop. Indefinitively. */
164  cycle() : HAsyncIterator<T>;
165
166  /** Group by objects by key according to returned key for each object. */
167  groupBy<K extends string | number | symbol>(callback: (value: T) => K | PromiseLike<K>) : Promise<{ [Key in K]: T[] }>;
168
169  /** Index this iterator objects in a {Map} with key obtained through {keyGetter}. */
170  toIndexedItems<K>(keyGetter: (value: T) => K | PromiseLike<K>) : Promise<Map<K, T>>;
171
172  /** Iterate over items present in both current collection and {otherItems} iterable. `O(n*m)` operation that will consume {otherItems} iterator/iterable! */
173  intersection<O>(
174    otherItems: AsyncIteratorOrIterable<O>,
175    isSameItemCallback: (value: T, other: O) => boolean | PromiseLike<boolean> = Object.is
176  ) : HAsyncIterator<T>;
177
178  /** Iterate over items present only in current collection, not in {otherItems} iterable. `O(n*m)` operation that will consume {otherItems} iterator/iterable! */
179  difference<O>(
180    otherItems: AsyncIteratorOrIterable<O>,
181    isSameItemCallback: (value: T, other: O) => boolean | PromiseLike<boolean> = Object.is
182  ) : HAsyncIterator<T>;
183
184  /** Iterate over items present only in current collection or only in {otherItems} iterable, but not in both. `O(n*m)` operation that will consume {otherItems} iterator/iterable! */
185  symmetricDifference<O>(
186    otherItems: AsyncIteratorOrIterable<O>,
187    isSameItemCallback: (value: T, other: O) => boolean | PromiseLike<boolean> = Object.is
188  ) : HAsyncIterator<T>;
189}

Helpers

iter function expose some iterator creator helpers:

• range
• repeat

There's presented as TypeScript types.

1// iter is instance of IIterFunction
2interface IIterFunction {
3  /** Create a new range `HIterator` from {0} to {stop}, 1 by 1. If {stop} is negative, it goes -1 by -1. */
4  range(stop: number): HIterator<number>;
5  /** Create a new range `HIterator` from {start} to {stop}, 1 by 1. If {stop} < {start}, it goes -1 by -1. */
6  range(start: number, stop: number): HIterator<number>;
7  /** Create a new range `HIterator` from {start} to {stop}, adding {step} at each step. */
8  range(start: number, stop: number, step: number): HIterator<number>;
9
10  /** Create a new `HIterator` that emit only {item} indefinitively. */
11  repeat<I>(item: I): HIterator<I>;
12  /** Create a new `HIterator` that emit only {item}, {times} times. */
13  repeat<I>(item: I, times: number): HIterator<I>;
14}

Examples

1for (const i of iter.range(10)) {
2  // i will goes from 0 to 9 (included)
3}
4
5for (const _ of iter.repeat(null, 10)) {
6  // This loop content will be executed 10 times
7}
8
9iter.repeat({ id: 1, name: 'Sialae' }) // Create an infinite iterator that yield { id: 1, name: 'Sialae' }
10  .asIndexedPairs() // Yield [index, element]
11  .map(([index, item]) => ({ ...item, id: index + 1 })) // For [index, element], returns { ...element, id: index + 1 }
12  .filter(item => item.id % 2 !== 0) // Yield only elements with element.id % 2 !== 0
13  .take(3) // Yield 3 items maximum then close the iterator
14  .toArray(); // Store the remaining iterator items into an array (3 elements)
15// Result: [{ name: 'Sialae', id: 1 }, { name: 'Sialae', id: 3 }, { name: 'Sialae', id: 5 }]

Descriptive API

Here's is every supported method, with a small example associated.

Sync iterators

Sync iterators uses the HIterator class/instances.

iter (module function)

Create the iterator wrapper HIterator from an Iterable (Array, Set, Map...) or an Iterator (Generator instance, user-land iterator, ...).

1import { iter } from 'iterator-helper'
2
3// From an iterable
4iter([1, 2, 3]) // => HIterator<1 | 2 | 3>
5
6// From an iterator
7iter([1, 2, 3].entries()) // => HIterator<[number, 1 | 2 | 3]>

.from (static method)

Do the same as iter function call. HIterator.from([1, 2, 3]) produces the same result as iter([1, 2, 3]).

.map<R>(callback: (value: T) => R) : HIterator<R, TReturn, TNext>

Transform each item of iterator to another value through the result of callback(item).

1iter([1, 2, 3])
2  .map(item => item * 2)
3  .toArray() // [2, 4, 6]

.filter(callback: (value: T) => boolean) : HIterator<T, TReturn, TNext>

Do not yield item of iterator if callback(item) is falsy.

1iter([1, 2, 3])
2  .filter(item => item % 2 !== 0)
3  .toArray() // [1, 3]

.take(limit: number) : HIterator<T, TReturn, TNext>

Create a new iterator that consume limit items, then stops.

1iter([1, 2, 3])
2  .take(2)
3  .toArray() // [1, 2]

.drop(limit: number) : HIterator<T, TReturn, TNext>

Create a new iterator that ignore limit items from being yielded, then continue the iterator as it used to be.

1iter([1, 2, 3])
2  .drop(2)
3  .toArray() // [3]

.asIndexedPairs() : HIterator<[number, T], TReturn, TNext>

Get a pair [index, value] for each value of an iterator.

1iter([1, 2, 3])
2  .asIndexedPairs()
3  .toArray() // [[0, 1], [1, 2], [2, 3]]

.flatMap<R>(mapper: (value: T) => Iterator<R> | R) : HIterator<R, TReturn, TNext>

Like map, but you can return a new iterator that will be flattened.

1iter([1, 2, 3])
2  .flatMap(item => iter.range(item))
3  .toArray() // [0, 0, 1, 0, 1, 2]

.find(callback: (value: T) => boolean) : T | undefined

Find a specific item that returns true in callback(item), and return it. Returns undefined otherwise.

1iter([1, 2, 3]).find(item => item % 2 === 0) // 2
2iter([1, 2, 3]).find(item => item % 2 === 4) // undefined

.findIndex(callback: (value: T) => boolean) : number

Find a specific item that returns true in callback(item), and return its index. Returns -1 otherwise.

1iter([1, 2, 3]).findIndex(item => item % 2 === 0) // 1
2iter([1, 2, 3]).findIndex(item => item % 2 === 4) // -1

.every(callback: (value: T) => boolean) : boolean

Return true if each item of iterator validate callback(item).

1iter([1, 2, 3]).every(item => item > 0) // true

.some(callback: (value: T) => boolean) : boolean

Return true if at least one item of iterator validate callback(item).

1iter([1, 2, 3]).every(item => item > 2) // true

.toArray(maxCount?: number) : T[]

Consume iterator (up to maxCount items, default to infinity) and collapse values inside an array.

1iter([1, 2, 3]).toArray() // [1, 2, 3]

.reduce<V>(reducer: (acc: V, value: T) => V, initialValue?: V) : V

Accumulate each item inside acc for each value value.

1iter([1, 2, 3]).reduce((acc, value) => acc + value) // 6

.forEach(callback: (value: T) => any) : void

Iterate over each value of iterator by calling callback for each item.

1iter([1, 2, 3]).forEach(console.log.bind(console)) // Logs 1, then 2, then 3

.count() : number

End the iterator and return the number of counted items.

1iter([1, 2, 3]).count() // 3

.join(glue: string) : string

Join all the remaining elements of the iterator in a single glue string glue.

1iter([1, 2, 3]).join(', ') // '1, 2, 3'

.chain<I>(...iterables: IteratorOrIterable<I>[]) : HIterator<T | I>

Iterate through current iterator, then through the given iterators in the correct order.

1iter([1, 2, 3])
2  .chain([4, 5, 6])
3  .toArray() // [1, 2, 3, 4, 5, 6]

.zip<O>(...others: IteratorOrIterable<O>[]) : HIterator<(T | O)[]>

Iterate through multiple iterators together.

1iter([1, 2, 3])
2  .zip([4, 5, 6])
3  .toArray() // [[1, 4], [2, 5], [3, 6]]

.takeWhile(callback: (value: T) => boolean) : HIterator<T>

Continue iterator until callback return a falsy value.

1iter([1, 2, 3])
2  .takeWhile(item => item / 2 > 1)
3  .toArray() // [1, 2]

.dropWhile(callback: (value: T) => boolean) : HIterator<T>

Skip elements until callback return a truthy value.

1iter([1, 2, 3])
2  .dropWhile(item => item / 2 <= 1)
3  .toArray() // [3]

.fuse() : HIterator<T>

Continue iterator until null or undefined is encountered.

1iter([1, 2, 3, undefined])
2  .fuse()
3  .toArray() // [1, 2, 3]

.partition(callback: (value: T) => boolean) : [T[], T[]]

Partition true elements to first array, false elements to second one.

1iter([1, 2, 3]).partition(item => item % 2 === 0) // [[2], [1, 3]]

.max() : number

Only works if it is a number iterator. Returns the maximum of iterator.

1iter([1, 2, 3]).max() // 3

.min() : number

Only works if it is a number iterator. Returns the minimum of iterator.

1iter([1, 2, 3]).min() // 1

.cycle() : HIterator<T>

When iterator ends, go back to the first item then loop. Indefinitively.

1iter([1, 2, 3])
2  .cycle()
3  .take(6)
4  .toArray() // [1, 2, 3, 1, 2, 3]

.groupBy<K extends string | number | symbol>(callback: (value: T) => K) : { [Key in K]: T[] }

Group by objects by key according to returned key for each object.

1iter([1, 2, 3]).groupBy(item => item % 2 === 0 ? 'even' : 'odd') // { even: [2], odd: [1, 3] }

.toIndexedItems<K>(keyGetter: (value: T) => K) : Map<K, T>

Index this iterator objects in a Map with key obtained through keyGetter.

1iter([1, 2, 3]).toIndexedItems(item => `key-${item}`) // Map<{ 'key-1': 1, 'key-2': 2, 'key-3': 3 }>

.intersection<O>(otherItems: IteratorOrIterable<O>, isSameItemCallback: (value: T, other: O) => boolean = Object.is) : HIterator<T>

Iterate over items present in both current collection and otherItems iterable. O(n*m) operation that will consume otherItems iterator/iterable!

1iter([1, 2, 3])
2  .intersection([3, 4, 5]) // equivalent to .intersection([3, 4, 5], (a, b) => Object.is(a, b))
3  .toArray() // [3]

.difference<O>(otherItems: IteratorOrIterable<O>, isSameItemCallback: (value: T, other: O) => boolean = Object.is) : HIterator<T>

Iterate over items present only in current collection, not in otherItems iterable. O(n*m) operation that will consume otherItems iterator/iterable!

1iter([1, 2, 3])
2  .difference([3, 4, 5]) // equivalent to .difference([3, 4, 5], (a, b) => Object.is(a, b))
3  .toArray() // [1, 2]

.symmetricDifference<O>(otherItems: IteratorOrIterable<O>, isSameItemCallback: (value: T, other: O) => boolean = Object.is) : HIterator<T>

Iterate over items present only in current collection or only in otherItems iterable. O(n*m) operation that will consume otherItems iterator/iterable!

1iter([1, 2, 3])
2  .symmetricDifference([3, 4, 5]) // equivalent to .symmetricDifference([3, 4, 5], (a, b) => Object.is(a, b))
3  .toArray() // [1, 2, 4, 5]

.toAsyncIterator(): HAsyncIterator<T>

Transform current sync iterator to an async one (wrap each new item into a resolved Promise). See below for available HAsyncIterator methods.

1iter([1, 2, 3]).toAsyncIterator() // HAsyncIterator<1 | 2 | 3>

Async iterators

Async iterators uses the HAsyncIterator class/instances.

Notice: The following async generator will be used in all async examples:

1async function* numbers() {
2  yield 1;
3  yield 2;
4  yield 3;
5}

Notice: In most of the cases, when a method takes a callback, the return value can be either a value or a Promise. If its a Promise, it will be awaited.

aiter (module function)

Create the iterator wrapper HAsyncIterator from an AsyncIterable (objects with Symbol.asyncIterator defined) or an AsyncIterator (AsyncGenerator instance, user-land async iterator, ...).

1import { aiter } from 'iterator-helper'
2
3// From an async iterable
4aiter({ 
5  async *[Symbol.asyncIterator]() {
6    yield* numbers();
7  } 
8}) // => HAsyncIterator<1 | 2 | 3>
9
10// From an iterator
11aiter(numbers()) // => HAsyncIterator<1 | 2 | 3>

.from (static method)

Do the same as aiter function call. HAsyncIterator.from(numbers()) produces the same result as aiter(numbers()).

.map<R>(callback: (value: T) => R | PromiseLike<R>) : HAsyncIterator<R, TReturn, TNext>

Transform each item of iterator to another value through the result of callback(item).

1aiter(numbers())
2  .map(item => item * 2)
3  .toArray() // Promise<[2, 4, 6]>

.filter(callback: (value: T) => boolean | PromiseLike<boolean>) : HAsyncIterator<T, TReturn, TNext>

Do not yield item of iterator if callback(item) is falsy.

1aiter(numbers())
2  .filter(item => item % 2 !== 0)
3  .toArray() // Promise<[1, 3]>

.take(limit: number) : HAsyncIterator<T, TReturn, TNext>

Create a new iterator that consume limit items, then stops.

1aiter(numbers())
2  .take(2)
3  .toArray() // Promise<[1, 2]>

.drop(limit: number) : HAsyncIterator<T, TReturn, TNext>

Create a new iterator that ignore limit items from being yielded, then continue the iterator as it used to be.

1aiter(numbers())
2  .drop(2)
3  .toArray() // Promise<[3]>

.asIndexedPairs() : HAsyncIterator<[number, T], TReturn, TNext>

Get a pair [index, value] for each value of an iterator.

1aiter(numbers())
2  .asIndexedPairs()
3  .toArray() // Promise<[[0, 1], [1, 2], [2, 3]]>

.flatMap<R>(mapper: (value: T) => AsyncIterator<R> | R) : HAsyncIterator<R, TReturn, TNext>

Like map, but you can return a new iterator that will be flattened.

1aiter(numbers())
2  .flatMap(item => iter.range(item).toAsyncIterator())
3  .toArray() // Promise<[0, 0, 1, 0, 1, 2]>

.find(callback: (value: T) => boolean | PromiseLike<boolean>) : Promise<T | undefined>

Find a specific item that returns true in callback(item), and return it. Returns undefined otherwise.

1aiter(numbers()).find(item => item % 2 === 0) // Promise<2>
2aiter(numbers()).find(item => item % 2 === 4) // Promise<undefined>

.findIndex(callback: (value: T) => boolean | PromiseLike<boolean>) : Promise<number>

Find a specific item that returns true in callback(item), and return its index. Returns -1 otherwise.

1aiter(numbers()).findIndex(item => item % 2 === 0) // Promise<1>
2aiter(numbers()).findIndex(item => item % 2 === 4) // Promise<-1>

.every(callback: (value: T) => boolean | PromiseLike<boolean>) : Promise<boolean>

Return true if each item of iterator validate callback(item).

1aiter(numbers()).every(item => item > 0) // Promise<true>

.some(callback: (value: T) => boolean | PromiseLike<boolean>) : Promise<boolean>

Return true if at least one item of iterator validate callback(item).

1aiter(numbers()).every(item => item > 2) // Promise<true>

.toArray(maxCount?: number) : Promise<T[]>

Consume iterator (up to maxCount items, default to infinity) and collapse values inside an array.

1aiter(numbers()).toArray() // Promise<[1, 2, 3]>

.reduce<V>(reducer: (acc: V, value: T) => V | PromiseLike<V>, initialValue?: V) : Promise<V>

Accumulate each item inside acc for each value value.

1aiter(numbers()).reduce((acc, value) => acc + value) // Promise<6>

.forEach(callback: (value: T) => any) : Promise<void>

Iterate over each value of iterator by calling callback for each item.

1aiter(numbers()).forEach(console.log.bind(console)) // Logs 1, then 2, then 3

.count() : Promise<number>

End the iterator and return the number of counted items.

1aiter(numbers()).count() // Promise<3>

.join(glue: string) : Promise<string>

Join all the remaining elements of the iterator in a single glue string glue.

1aiter(numbers()).join(', ') // Promise<'1, 2, 3'>

.chain<I>(...iterables: AsyncIteratorOrIterable<I>[]) : HAsyncIterator<T | I>

Iterate through current iterator, then through the given iterators in the correct order.

1aiter(numbers())
2  .chain(iter([4, 5, 6]).toAsyncIterator())
3  .toArray() // Promise<[1, 2, 3, 4, 5, 6]>

.zip<O>(...others: AsyncIteratorOrIterable<O>[]) : HAsyncIterator<(T | O)[]>

Iterate through multiple iterators together.

1aiter(numbers())
2  .zip(iter([4, 5, 6]).toAsyncIterator()])
3  .toArray() // Promise<[[1, 4], [2, 5], [3, 6]]>

.takeWhile(callback: (value: T) => boolean | PromiseLike<boolean>) : HAsyncIterator<T>

Continue iterator until callback return a falsy value.

1aiter(numbers())
2  .takeWhile(item => item / 2 > 1)
3  .toArray() // Promise<[1, 2]>

.dropWhile(callback: (value: T) => boolean | PromiseLike<boolean>) : HAsyncIterator<T>

Skip elements until callback return a truthy value.

1aiter(numbers())
2  .dropWhile(item => item / 2 <= 1)
3  .toArray() // Promise<[3]>

.fuse() : HAsyncIterator<T>

Continue iterator until null or undefined is encountered.

1iter([1, 2, 3, undefined])
2  .toAsyncIterator()
3  .fuse()
4  .toArray() // Promise<[1, 2, 3]>

.partition(callback: (value: T) => boolean | PromiseLike<boolean>) : Promise<[T[], T[]]>

Partition true elements to first array, false elements to second one.

1aiter(numbers()).partition(item => item % 2 === 0) // Promise<[[2], [1, 3]]>

.max() : Promise<number>

Only works if it is a number iterator. Returns the maximum of iterator.

1aiter(numbers())).max() // Promise<3>

.min() : Promise<number>

Only works if it is a number iterator. Returns the minimum of iterator.

1aiter(numbers()).min() // Promise<1>

.cycle() : HAsyncIterator<T>

When iterator ends, go back to the first item then loop. Indefinitively.

1aiter(numbers())
2  .cycle()
3  .take(6)
4  .toArray() // Promise<[1, 2, 3, 1, 2, 3]>

.groupBy<K extends string | number | symbol>(callback: (value: T) => K | PromiseLike<K>) : Promise<{ [Key in K]: T[] }>

Group by objects by key according to returned key for each object.

1aiter(numbers())
2  .groupBy(item => item % 2 === 0 ? 'even' : 'odd') // Promise<{ even: [2], odd: [1, 3] }>

.toIndexedItems<K>(keyGetter: (value: T) => K | PromiseLike<K>) : Promise<Map<K, T>>

Index this iterator objects in a Map with key obtained through keyGetter.

1aiter(numbers())
2  .toIndexedItems(item => `key-${item}`) // Promise<Map<{ 'key-1': 1, 'key-2': 2, 'key-3': 3 }>>

.intersection<O>(otherItems: AsyncIteratorOrIterable<O>, isSameItemCallback: (value: T, other: O) => boolean | PromiseLike<boolean> = Object.is) : HAsyncIterator<T>

Iterate over items present in both current collection and otherItems iterable. O(n*m) operation that will consume otherItems iterator/iterable!

1aiter(numbers())
2  .intersection(iter([3, 4, 5]).toAsyncIterator())
3  .toArray() // Promise<[3]>

.difference<O>(otherItems: AsyncIteratorOrIterable<O>, isSameItemCallback: (value: T, other: O) => boolean | PromiseLike<boolean> = Object.is) : HAsyncIterator<T>

Iterate over items present only in current collection, not in otherItems iterable. O(n*m) operation that will consume otherItems iterator/iterable!

1aiter(numbers())
2  .difference(iter([3, 4, 5]).toAsyncIterator())
3  .toArray() // Promise<[1, 2]>

.symmetricDifference<O>(otherItems: AsyncIteratorOrIterable<O>, isSameItemCallback: (value: T, other: O) => boolean | PromiseLike<boolean> = Object.is) : HAsyncIterator<T>

Iterate over items present only in current collection or only in otherItems iterable. O(n*m) operation that will consume otherItems iterator/iterable!

1aiter(numbers())
2  .symmetricDifference(iter([3, 4, 5]).toAsyncIterator()) 
3  .toArray() // Promise<[1, 2, 4, 5]>

Iterator creators

iter.range

Create a range iterator (HIterator instance) from:

• 0 to stop if only stop is specified, from (-)1 by (-)1.
• start to stop, from (-)1 by (-)1 or from step to step

1for (const i of iter.range(10)) {
2  // i goes from 0 to 9 included, 1 by 1.
3}
4
5for (const i of iter.range(0, 10, 2)) {
6  // i takes 0, 2, 4, 6, 8 as value
7}
8
9for (const i of iter.range(1, 10)) {
10  // i goes from 1 to 9 included, 1 by 1.
11}
12
13for (const i of iter.range(-10)) {
14  // i goes from 0 to -9 included, -1 by -1.
15}
16
17for (const i of iter.range(20, 10)) {
18  // i goes from 20 to 11 included, -1 by -1.
19}

iter.repeat

Create an finite or infinite iterator that constantly yield the same thing.

1iter.repeat({ id: 1 }) // Will yield { id: 1 } indefinitively
2// or
3iter.repeat({ id: 1 }, 5) // Will yield { id: 1 } 5 times, then stops

this is equal to this code:

1iter([{ id: 1 }]).cycle()
2// or
3iter([{ id: 1 }]).cycle().take(5)