Iterative

Functions for working with iterators in JavaScript, with TypeScript.

(Inspired by itertools)

Installation

npm install iterative --save

Usage

🚨 The packages comes in two flavors, Iterator and AsyncIterator. Use iterative/dist/async for async iterators. 🚨

range(start = 0, stop = Infinity, step = 1): Iterable<number>

This is a versatile function to create lists containing arithmetic progressions.

range(); //=> [0, 1, 2, 3, 4, 5, 6, 7, 8, ...]
range(10, 20, 5); //=> [10, 15]

cycle<T>(iterable: Iterable<T>): Iterable<T>

Make an iterator returning elements from the iterable and saving a copy of each. When the iterable is exhausted, return elements from the saved copy. Repeats indefinitely.

cycle([1, 2, 3]); //=> [1, 2, 3, 1, 2, 3, 1, 2, ...]

repeat<T>(value: T, times?: number): Iterable<T>

Make an iterator that repeats value over and over again.

repeat(true); //=> [true, true, true, true, ...]

flatten<T>(iterable: Iterable<Iterable<T>>): Iterable<T>

Return an iterator flattening one level of nesting in an iterable of iterables.

flatten([[1, 2, 3], [4, 5, 6], [7, 8, 9]]); //=> [1, 2, 3, 4, 5, 6, 7, 8, 9]

chain<T>(...iterables: Array<Iterable<T>>): Iterable<T>

Make an iterator that returns elements from the first iterable until it is exhausted, then proceeds to the next iterable, until all of the iterables are exhausted. Used for treating consecutive sequences as a single sequence.

chain([1, 2, 3], [4, 5, 6], [7, 8, 9]); //=> [1, 2, 3, 4, 5, 6, 7, 8, 9]

slice<T>(iterable: Iterable<T>, start = 0, stop = Infinity, step = 1): Iterable<T>

Make an iterator that returns selected elements from the iterable.

slice([1, 2, 3, 4, 5]); //=> [1, 2, 3, 4, 5]
slice(range(), 2, 5); //=> [2, 3, 4]

map<T, U>(iterable: Iterable<T>, func: (x: T) => U): Iterable<U>

Apply function to every item of iterable and return an iterable of the results.

map([1, 2, 3], x => x * x); //=> [1, 4, 9]

spreadmap<T, U>(iterable: Iterable<T>, func: (...args: T) => U): Iterable<U>

Make an iterator that computes the function using arguments obtained from the iterable. Used instead of map() when argument parameters are already grouped in tuples from a single iterable (the data has been "pre-zipped"). The difference between map() and spreadmap() parallels the distinction between function(a, b) and function(...c).

map([[1, 2], [3, 4], [5, 6]], (a, b) => a + b); //=> [3, 7, 11]

filter<T, U extends T>(iterable: Iterable<T>, func: Predicate<T, U> = Boolean): Iterable<U>

Construct an iterator from those elements of iterable for which func returns true.

filter(range(0, 10), x => x % 2 === 0); //=> [0, 2, 4, 6, 8]

reduce<T, U>(iterable: Iterable<T>, reducer: Reducer<T, U>, initializer?: U): U

Apply function of two arguments cumulatively to the items of iterable, from left to right, so as to reduce the iterable to a single value.

reduce([1, 2, 3], (sum, val) => sum + val); //=> 6

accumulate<T>(iterable: Iterable<T>, func: Reducer<T, T>): Iterable<T>

Make an iterator that returns accumulated results of binary functions.

accumulate([1, 2, 3], (sum, val) => sum + val); //=> [1, 3, 6]

all<T, U extends T>(iterable: Iterable<T>, predicate: Predicate<T, U> = Boolean): boolean

Returns true when all values in iterable are truthy.

all([1, 2, 3], x => x % 2 === 0); //=> false

any<T, U extends T>(iterable: Iterable<T>, predicate: Predicate<T, U> = Boolean): boolean

Returns true when any value in iterable is truthy.

any([1, 2, 3], x => x % 2 === 0); //=> true

contains<T>(iterable: Iterable<T>, needle: T): boolean

Returns true when any value in iterable is equal to needle.

contains("test", "t"); //=> true

dropWhile<T>(iterable: Iterable<T>, predicate: Predicate<T>): Iterable<T>

Make an iterator that drops elements from the iterable as long as the predicate is true; afterwards, returns every element.

dropWhile([1, 2, 3, 4, 5], x => x < 3); //=> [3, 4, 5]

takeWhile<T>(iterable: Iterable<T>, predicate: Predicate<T>): Iterable<T>

Make an iterator that returns elements from the iterable as long as the predicate is true.

takeWhile([1, 2, 3, 4, 5], x => x < 3); //=> [1, 2]

groupBy<T, U>(iterable: Iterable<T>, func: (x: T) => U): Iterable<[U, Iterable<T>]>

Make an iterator that returns consecutive keys and groups from the iterable. The func is a function computing a key value for each element.

groupBy(range(0, 6), x => Math.floor(x / 2)); //=> [[0, [0, 1]], [1, [2, 3]], [2, [4, 5]]]

enumerate<T>(iterable: Iterable<T>, offset = 0): Iterable<[number, T]>

Returns an iterable of enumeration pairs.

enumerate("test"); //=> [[0, 't'], [1, 'e'], [2, 's'], [3, 't']]

zip<T>(...iterables: Iterable<T>[]): Iterable<T[]>

Returns an iterator of tuples, where the i-th tuple contains the i-th element from each of the argument sequences or iterables. The iterator stops when the shortest input iterable is exhausted.

zip([1, 2, 3], ["a", "b", "c"]); //=> [[1, 'a'], [2, 'b'], [3, 'c']]

zipLongest<T>(...iterables: Iterable<T>[]): Iterable<(T | undefined)[]>

Make an iterator that aggregates elements from each of the iterables. If the iterables are of uneven length, missing values are undefined. Iteration continues until the longest iterable is exhausted.

zipLongest([1, 2], ["a", "b", "c", "d"]); //=> [[1, 'a'], [2, 'b'], [undefined, 'c'], [undefined, 'd']]

zipWithValue<T, U>(fillValue: U, iterables: Iterable<T>[]): Iterable<(T | U)[]>

Make an iterator that aggregates elements from each of the iterables. If the iterables are of uneven length, missing values are fillValue. Iteration continues until the longest iterable is exhausted.

zipWithValue("example", [1, 2], ["a", "b", "c", "d"]); //=> [[1, 'a'], [2, 'b'], ['example', 'c'], ['example', 'd']]

tee<T>(iterable: Iterable<T>): [Iterable<T>, Iterable<T>]

Return two independent iterables from a single iterable.

tee([1, 2, 3]); //=> [[1, 2, 3], [1, 2, 3]]

chunk<T>(iterable: Iterable<T>, size: number): Iterable<T[]>

Break iterable into lists of length size.

chunk(range(0, 10), 2); //=> [[0, 1], [2, 3], [4, 5], [6, 7], [8, 9]]

pairwise<T>(iterable: Iterable<T>): Iterable<[T, T]>

Returns an iterator of paired items, overlapping, from the original. When the input iterable has a finite number of items n, the outputted iterable will have n - 1 items.

pairwise(range(0, 5)); //=> [[0, 1], [1, 2], [2, 3], [3, 4]]

compress<T>(iterable: Iterable<T>, selectors: Iterable<boolean>): Iterable<T>

Make an iterator that filters elements from iterable returning only those that have a corresponding element in selectors that evaluates to true.

compress([1, 2, 3, 4, 5], [true, false, true, false, true]); //=> [1, 3, 5]

sorted<T, U>(iterable: Iterable<T>, key: (x: T) => U, cmp: (x: U, y: U) => number, reverse?: boolean): T[]

Return a sorted array from the items in iterable.

sorted(slice(range(), 0, 10), x => x);

list<T>(iterable: Iterable<T>): T[]

Creates an array from an iterable object.

list(range(0, 5)); //=> [0, 1, 2, 3, 4]

dict<K, V>(iterable: Iterable<[K, V]>): Record<K, V>

Return an object from an iterable, i.e. Array.from for objects.

dict(zip(range(0, 5), repeat(true))); //=> { 0: true, 1: true, 2: true, 3: true, 4: true }

len(iterable: Iterable<any>): number

Return the length (the number of items) of an iterable.

len(range(0, 5)); //=> 5

Note: This method iterates over iterable to return the length.

min<T>(iterable: Iterable<T>, key?: (x: T) => number): T

Return the smallest item in an iterable.

min([1, 2, 3, 4, 5]); //=> 1

max<T>(iterable: Iterable<T>, key?: (x: T) => number): T

Return the largest item in an iterable.

max([1, 2, 3, 4, 5]); //=> 5

sum(iterable: Iterable<number>, start?: number): number

Sums start and the items of an iterable from left to right and returns the total.

sum([1, 2, 3, 4, 5]); //=> 15

product<T>(...iterables: Iterable<T>[]): Iterable<T[]>

Cartesian product of input iterables.

product("ABCD", "xy"); //=> Ax Ay Bx By Cx Cy Dx Dy

Reference

• Itertools Recipes

TypeScript

This project uses TypeScript and publishes definitions on NPM.

License

Apache 2.0