Package Exports

itertools-ts
itertools-ts/es/index.js
itertools-ts/lib/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (itertools-ts) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

IterTools implementation for TypeScript

Inspired by Python — designed for TypeScript.

Features

IterTools makes you an iteration superstar by providing two types of tools:

Loop iteration tools
Stream iteration tools

Loop Iteration Tools Example

import { multi } from 'itertools-ts';

for (const [letter, number] of multi.zip(['a', 'b'], [1, 2])) {
  console.log(`${letter}${number}`);  // a1, b2
}

Stream Iteration Tools Example

import { Stream } from 'itertools-ts';

const result = Stream.of([1, 1, 2, 2, 3, 4, 5])
  .distinct()             // [1, 2, 3, 4, 5]
  .map((x) => x**2)       // [1, 4, 9, 16, 25]
  .filter((x) => x < 10)  // [1, 4, 9]
  .toSum();               // 14

All functions work on iterable collections and iterators:

Array
Set
Map
String
Generator
Iterable
Iterator

Setup

npm i itertools-ts

Quick Reference

Loop Iteration Tools

Multi Iteration

Iterator	Description	Code Snippet
`chain`	Chain multiple iterables together	`multi.chain(list1, list2, ...)`
`zip`	Iterate multiple collections simultaneously until the shortest iterator completes	`multi.zip(list1, list2, ...)`
`zipEqual`	Iterate multiple collections of equal length simultaneously, error if lengths not equal	`multi.zipEqual(list1, list2, ...)`
`zipLongest`	Iterate multiple collections simultaneously until the longest iterator completes	`multi.zipLongest(list1, list2, ...)`

Single Iteration

Iterator	Description	Code Snippet
`chunkwise`	Iterate by chunks	`single.chunkwise(data, chunkSize)`
`chunkwiseOverlap`	Iterate by overlapped chunks	`single.chunkwiseOverlap(data, chunkSize, overlapSize)`
`enumerate`	Enumerates elements of collection	`single.enumerate(data)`
`filter`	Filter for elements where predicate is true	`single.filter(data, predicate)`
`flatMap`	Map function onto items and flatten result	`single.flatMap(data, mapper)`
`flatten`	Flatten multidimensional iterable	`single.flatten(data, [dimensions])`
`limit`	Iterate up to a limit	`single.limit(data, limit)`
`keys`	Iterate keys of key-value pairs	`single.keys(data)`
`map`	Map function onto each item	`single.map(data, mapper)`
`pairwise`	Iterate successive overlapping pairs	`single.pairwise(data)`
`repeat`	Repeat an item a number of times	`single.repeat(item, repetitions)`
`slice`	Extract a slice of the iterable	`single.slice(data, [start], [count], [step])`
`values`	Iterate values of key-value pairs	`single.values(data)`

Reduce

Reducer	Description	Code Snippet
`toCount`	Reduce to length of iterable	`reduce.toCount(data)`
`toMax`	Reduce to its greatest element	`reduce.toMax(numbers, [compareBy])`
`toMin`	Reduce to its smallest element	`reduce.toMin(numbers, [compareBy])`
`toProduct`	Reduce to the product of its elements	`reduce.toProduct(numbers)`
`toSum`	Reduce to the sum of its elements	`reduce.toSum(numbers)`
`toValue`	Reduce to value using callable reducer	`reduce.toValue(data, reducer, initialValue)`

Set and multiset Iteration

Iterator	Description	Code Snippet
`distinct`	Iterate only distinct items	`set.distinct(data)`

Summary

Summary	Description	Code Snippet
`isIterable`	True if given data is iterable	`summary.isIterable(data)`
`isIterator`	True if given data is iterator	`summary.isIterator(data)`

Transform

Iterator	Description	Code Snippet
`toArray`	Transforms collection to array	`transform.toArray(data)`
`toIterable`	Transforms collection to iterable	`transform.toIterable(data)`
`toIterator`	Transforms collection to iterator	`transform.toIterator(data)`

Stream Iteration Tools

Stream Sources

Source	Description	Code Snippet
`of`	Create a stream from an iterable	`Stream.of(iterable)`
`ofEmpty`	Create an empty stream	`Stream.ofEmpty()`

Stream Operations

Operation	Description	Code Snippet
`chainWith`	Chain iterable source withs given iterables together into a single iteration	`stream.chainWith(...iterables)`
`chunkwise`	Iterate by chunks	`stream.chunkwise(chunkSize)`
`chunkwiseOverlap`	Iterate by overlapped chunks	`stream.chunkwiseOverlap(chunkSize, overlap)`
`distinct`	Filter out elements: iterate only unique items	`stream.distinct()`
`enumerate`	Enumerates elements of stream	`stream.enumerate()`
`filter`	Filter for only elements where the predicate function is true	`stream.filter(predicate)`
`flatMap`	Map function onto elements and flatten result	`stream.flatMap(mapper)`
`flatten`	Flatten multidimensional stream	`stream.flatten([dimensions])`
`keys`	Iterate keys of key-value pairs from stream	`stream.keys()`
`limit`	Limit the stream's iteration	`stream.limit(limit)`
`map`	Map function onto elements	`stream.map(mapper)`
`pairwise`	Return pairs of elements from iterable source	`stream.pairwise()`
`slice`	Extract a slice of the stream	`stream.slice([start], [count], [step])`
`values`	Iterate values of key-value pairs from stream	`stream.values()`
`zipWith`	Iterate iterable source with another iterable collections simultaneously	`stream.zipWith(...iterables)`
`zipLongestWith`	Iterate iterable source with another iterable collections simultaneously	`stream.zipLongestWith(...iterables)`
`zipEqualWith`	Iterate iterable source with another iterable collections of equal lengths simultaneously	`stream.zipEqualWith(...iterables)`

Stream Terminal Operations

Transformation Terminal Operations

Terminal Operation	Description	Code Snippet
`toArray`	Returns array of stream elements	`stream.toArray()`

Reduction Terminal Operations

Terminal Operation	Description	Code Snippet
`toCount`	Reduces stream to its length	`stream.toCount()`
`toMax`	Reduces stream to its max value	`stream.toMax([compareBy])`
`toMin`	Reduces stream to its min value	`stream.toMin([compareBy])`
`toProduct`	Reduces stream to the product of its items	`stream.toProduct()`
`toSum`	Reduces stream to the sum of its items	`stream.toSum()`
`toValue`	Reduces stream like array.reduce() function	`stream.toValue(reducer, initialValue)`

Usage

Multi Iteration

Chain

Chain multiple iterables together into a single continuous sequence.

function *chain(
  ...iterables: Array<Iterable<unknown>|Iterator<unknown>>
): Iterable<unknown>

import { multi } from 'itertools-ts';

const prequels = ['Phantom Menace', 'Attack of the Clones', 'Revenge of the Sith'];
const originals = ['A New Hope', 'Empire Strikes Back', 'Return of the Jedi'];

for (const movie of multi.chain(prequels, originals)) {
  console.log(movie);
}
// 'Phantom Menace', 'Attack of the Clones', 'Revenge of the Sith', 'A New Hope', 'Empire Strikes Back', 'Return of the Jedi'

Zip

Iterate multiple iterable collections simultaneously.

function *zip(
  ...iterables: Array<Iterable<unknown>|Iterator<unknown>>
): Iterable<Array<unknown>>

import { multi } from 'itertools-ts';

const languages = ['PHP', 'Python', 'Java', 'Go'];
const mascots = ['elephant', 'snake', 'bean', 'gopher'];

for (const [language, mascot] of multi.zip(languages, mascots)) {
  console.log(`The ${language} language mascot is an ${mascot}.`);
}
// The PHP language mascot is an elephant.
// ...

Zip works with multiple iterable inputs - not limited to just two.

import { multi } from 'itertools-ts';

const names          = ['Ryu', 'Ken', 'Chun Li', 'Guile'];
const countries      = ['Japan', 'USA', 'China', 'USA'];
const signatureMoves = ['hadouken', 'shoryuken', 'spinning bird kick', 'sonic boom'];

for (const [name, country, signatureMove] of multi.zip(names, countries, signatureMoves)) {
  const streetFighter = new StreetFighter(name, country, signatureMove);
}

Note: For uneven lengths, iteration stops when the shortest iterable is exhausted.

Zip Longest

Iterate multiple iterable collections simultaneously.

function *zipLongest(
  ...iterables: Array<Iterable<unknown>|Iterator<unknown>>
): Iterable<Array<unknown>>

For uneven lengths, the exhausted iterables will produce undefined for the remaining iterations.

import { multi } from 'itertools-ts';

const letters = ['A', 'B', 'C'];
const numbers = [1, 2];

for (const [letter, number] of multi.zipLongest(letters, numbers)) {
  // ['A', 1], ['B', 2], ['C', undefined]
}

Zip Equal

Iterate multiple iterable collections with equal lengths simultaneously.

Throws LengthException if lengths are not equal, meaning that at least one iterator ends before the others.

function *zipEqual(
  ...iterables: Array<Iterable<unknown>|Iterator<unknown>>
): Iterable<Array<unknown>>

import { multi } from 'itertools-ts';

const letters = ['A', 'B', 'C'];
const numbers = [1, 2, 3];

for (const [letter, number] of multi.zipEqual(letters, numbers)) {
    // ['A', 1], ['B', 2], ['C', 3]
}

Single Iteration

Chunkwise

Return elements in chunks of a certain size.

function *chunkwise<T>(
  data: Iterable<T>|Iterator<T>, 
  chunkSize: number,
): Iterable<Array<T>>

Chunk size must be at least 1.

import { single } from 'itertools-ts';

const movies = [
    'Phantom Menace', 'Attack of the Clones', 'Revenge of the Sith',
    'A New Hope', 'Empire Strikes Back', 'Return of the Jedi',
    'The Force Awakens', 'The Last Jedi', 'The Rise of Skywalker',
];
const trilogies = [];

for (const trilogy of single.chunkwise(movies, 3)) {
    trilogies.push(trilogy);
}
// [
//     ['Phantom Menace', 'Attack of the Clones', 'Revenge of the Sith'],
//     ['A New Hope', 'Empire Strikes Back', 'Return of the Jedi'],
//     ['The Force Awakens', 'The Last Jedi', 'The Rise of Skywalker]',
// ]

Chunkwise Overlap

Return overlapped chunks of elements.

function *chunkwiseOverlap<T>(
  data: Iterable<T>|Iterator<T>,
  chunkSize: number,
  overlapSize: number,
  includeIncompleteTail: boolean = true,
): Iterable<Array<T>>

Chunk size must be at least 1.
Overlap size must be less than chunk size.

import { single } from 'itertools-ts';

const numbers = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];

for (const chunk of single.chunkwiseOverlap(numbers, 3, 1)) {
  // [1, 2, 3], [3, 4, 5], [5, 6, 7], [7, 8, 9], [9, 10]
}

Enumerate

Enumerates elements of given collection.

function *enumerate<T>(data: Iterable<T>|Iterator<T>): Iterable<[number, T]>

import { single } from 'itertools-ts';

const letters = ['a', 'b', 'c', 'd', 'e'];

for (const item of single.enumerate(letters)) {
  // [[0, 'a'], [1, 'b'], [2, 'c'], [3, 'd'], [4, 'e']]
}

Filter

Filter out elements from the iterable only returning elements where the predicate function is true.

function *filter<T>(
  data: Iterable<T>|Iterator<T>,
  predicate: (datum: T) => boolean,
): Iterable<T>

import { single } from 'itertools-ts';

const starWarsEpisodes = [1, 2, 3, 4, 5, 6, 7, 8, 9];
const goodMoviePredicate = (episode) => episode > 3 && episode < 8;

for (const goodMovie of single.filter(starWarsEpisodes, goodMoviePredicate)) {
  console.log(goodMovie);
}
// 4, 5, 6, 7

Flat Map

Map a function only the elements of the iterable and then flatten the results.

function *flatMap<TInput, TOutput>(
  data: Iterable<TInput>|Iterator<TInput>,
  mapper: FlatMapper<TInput, TOutput>,
): Iterable<TOutput>

import { single } from 'itertools-ts';

const data = [1, 2, 3, 4, 5];
const mapper = (item) => [item, -item];

for (number of single.flatMap(data, mapper)) {
  console.log(number);
}
// 1 -1 2 -2 3 -3 4 -4 5 -5

Flatten

Flatten a multidimensional iterable.

function *flatten(
  data: Iterable<unknown>|Iterator<unknown>,
  dimensions: number = Infinity,
): Iterable<unknown>

import { single } from 'itertools-ts';

const multidimensional = [1, [2, 3], [4, 5]];

const flattened = [];
for (const number of single.flatten(multidimensional)) {
    flattened.push(number);
}
// [1, 2, 3, 4, 5]

Keys

Iterate keys of key-value pairs.

function *keys<TKey, TValue>(
  collection: Iterable<[TKey, TValue]>|Iterator<[TKey, TValue]>,
): Iterable<TKey>

import { single } from 'itertools-ts';

const dict = new Map([['a', 1], ['b', 2], ['c', 3]]);

for (const key of single.keys(dict)) {
  console.log(key);
}
// 'a', 'b', 'c'

Limit

Iterate up to a limit.

Stops even if more data available if limit reached.

function *limit<T>(data: Iterable<T>|Iterator<T>, count: number): Iterable<T>

import { single } from 'itertools-ts';

const matrixMovies = ['The Matrix', 'The Matrix Reloaded', 'The Matrix Revolutions', 'The Matrix Resurrections'];
const limit = 1;

for (const goodMovie of single.limit(matrixMovies, limit)) {
    console.log(goodMovie);
}
// 'The Matrix' (and nothing else)

Map

Map a function onto each element.

function *map<TInput, TOutput>(
  data: Iterable<TInput>|Iterator<TInput>,
  mapper: (datum: TInput) => TOutput,
): Iterable<TOutput>

import { single } from 'itertools-ts';

const grades = [100, 99, 95, 98, 100];
const strictParentsOpinion = (g) => (g === 100) ? 'A' : 'F';

for (const actualGrade of single.map(grades, strictParentsOpinion)) {
  console.log(actualGrade);
}
// A, F, F, F, A

Pairwise

Returns successive overlapping pairs.

Returns empty generator if given collection contains fewer than 2 elements.

function *pairwise<T>(data: Iterable<T>|Iterator<T>): Iterable<Pair<T>>

import { single } from 'itertools-ts';

const friends = ['Ross', 'Rachel', 'Chandler', 'Monica', 'Joey', 'Phoebe'];

for (const [leftFriend, rightFriend] of single.pairwise(friends)) {
  console.log(`${leftFriend} and ${rightFriend}`);
}
// Ross and Rachel, Rachel and Chandler, Chandler and Monica, ...

Repeat

Repeat an item.

function *repeat<T>(item: T, repetitions: number): Iterable<T>

import { single } from 'itertools-ts';

data = 'Beetlejuice';
repetitions = 3;

for (const repeated of single.repeat(data, repetitions)) {
  console.log(repeated);
}
// 'Beetlejuice', 'Beetlejuice', 'Beetlejuice'

Slice

Extract a slice of the iterable.

function *slice<T>(
  data: Iterable<T>|Iterator<T>,
  start: number = 0,
  count?: number,
  step: number = 1,
): Iterable<T>

import { single } from 'itertools-ts';

const olympics = [1992, 1994, 1996, 1998, 2000, 2002, 2004, 2006, 2008, 2010, 2012, 2014, 2016, 2018, 2020, 2022];
const winterOlympics = [];

for (const winterYear of single.slice(olympics, 1, 8, 2)) {
    winterOlympics.push(winterYear);
}
// [1994, 1998, 2002, 2006, 2010, 2014, 2018, 2022]

Values

Iterate values of key-value pairs.

function *values<TKey, TValue>(
  collection: Iterable<[TKey, TValue]>|Iterator<[TKey, TValue]>,
): Iterable<TValue>

import { single } from 'itertools-ts';

const dict = new Map([['a', 1], ['b', 2], ['c', 3]]);

for (const value of single.keys(dict)) {
  console.log(value);
}
// 1, 2, 3

Reduce

To Count

Reduces iterable to its length.

function toCount(data: Iterable<unknown>|Iterator<unknown>): number

import { reduce } from 'itertools-ts';

const data = [1, 2, 3];

const length = reduce.toCount(data);
// 3

To Max

Reduces to the max value.

function toMax<TValue, TComparable>(
  data: Iterable<TValue>|Iterator<TValue>,
  compareBy?: (datum: TValue) => TComparable,
): TValue|undefined

Optional callable param compareBy must return comparable value.
If compareBy is not provided then items of given collection must be comparable.
Returns undefined if collection is empty.

import { reduce } from 'itertools-ts';

const numbers = [5, 3, 1, 2, 4];

const result = reduce.toMax(numbers);
// 1

const movieRatings = [
  {
    title: 'The Matrix',
    rating: 4.7,
  },
  {
    title: 'The Matrix Reloaded',
    rating: 4.3,
  },
  {
    title: 'The Matrix Revolutions',
    rating: 3.9,
  },
  {
    title: 'The Matrix Resurrections',
    rating: 2.5,
  },
];
const compareBy = (movie) => movie.rating;

const lowestRatedMovie = reduce.toMin(movieRatings, compareBy);
// {
//   title: 'The Matrix',
//   rating: 4.7,
// }

To Min

Reduces to the min value.

function toMin<TValue, TComparable>(
  data: Iterable<TValue>|Iterator<TValue>,
  compareBy?: (datum: TValue) => TComparable,
): TValue|undefined

Optional callable param compareBy must return comparable value.
If compareBy is not provided then items of given collection must be comparable.
Returns undefined if collection is empty.

import { reduce } from 'itertools-ts';

const numbers = [5, 3, 1, 2, 4];

const result = reduce.toMin(numbers);
// 1

const movieRatings = [
  {
    title: 'The Matrix',
    rating: 4.7,
  },
  {
    title: 'The Matrix Reloaded',
    rating: 4.3,
  },
  {
    title: 'The Matrix Revolutions',
    rating: 3.9,
  },
  {
    title: 'The Matrix Resurrections',
    rating: 2.5,
  },
];
const compareBy = (movie) => movie.rating;

const lowestRatedMovie = reduce.toMin(movieRatings, compareBy);
// {
//   title: 'The Matrix Resurrections',
//   rating: 2.5,
// }

To Product

Reduces to the product of its elements.

Returns undefined if collection is empty.

function toProduct(data: Iterable<number>|Iterator<number>): number|undefined

import { reduce } from 'itertools-ts';

const primeFactors = [5, 2, 2];

const number = reduce.toProduct(primeFactors);
// 20

To Sum

Reduces to the sum of its elements.

function toSum(data: Iterable<number>|Iterator<number>): number

import { reduce } from 'itertools-ts';

const parts = [10, 20, 30];

const sum = reduce.toSum(parts);
// 60

To Value

Reduce elements to a single value using reducer function.

function toValue<TInput, TOutput>(
  data: Iterable<TInput>|Iterator<TInput>,
  reducer: (carry: TOutput|undefined, datum: TInput) => TOutput,
  initialValue?: TOutput,
): TOutput|undefined

import { reduce } from 'itertools-ts';

const input = [1, 2, 3, 4, 5];
const sum = (carry, item) => carry + item;

const result = reduce.toValue(input, sum, 0);
// 15

Set and multiset

Distinct

Filter out elements from the iterable only returning distinct elements.

function *distinct<T>(data: Iterable<T>|Iterator<T>): Iterable<T>

import { set } from 'itertools-ts';

const chessSet = ['rook', 'rook', 'knight', 'knight', 'bishop', 'bishop', 'king', 'queen', 'pawn', 'pawn'];

for (const chessPiece of set.distinct(chessSet)) {
  console.log(chessPiece);
}
// rook, knight, bishop, king, queen, pawn

Summary

Is Iterable

Returns true if given data is an Iterable instance.

function isIterable(input: unknown): boolean

import { summary } from "itertools-ts";

const input = [1, 2, 3, 4, 5];

summary.isIterable(input); // true
summary.isIterable(input[Symbol.iterator]()) // false
summary.isIterable(1); // false

Is Iterator

Returns true if given data is an Iterator instance.

function isIterator(input: unknown): boolean

import { summary } from "itertools-ts";

const input = [1, 2, 3, 4, 5];

summary.isIterator(input[Symbol.iterator]()) // true
summary.isIterator(input); // false
summary.isIterator(1); // false

Transform

To Iterable

Returns Iterable instance of given collection or iterator.

Throws InvalidArgumentError if given data is not a collection or an iterator.

function toIterable<T>(collection: Iterable<T>|Iterator<T>): Iterable<T>

import { transform } from "itertools-ts";

const input = [1, 2, 3, 4, 5];

const result = transform.toIterable(input);
// [1, 2, 3, 4, 5]

To Array

Returns Array instance of given collection or iterator.

function toArray<T>(collection: Iterable<T>|Iterator<T>): Array<T>

import { transform } from "itertools-ts";

const iterator = transform.toIterator([1, 2, 3, 4, 5]);

const result = transform.toArray(iterator);
// [1, 2, 3, 4, 5]

To Iterator

Returns Iterator instance of given collection or iterator.

Throws InvalidArgumentError if given data is not a collection or an iterator.

function toIterator<T>(collection: Iterable<T>|Iterator<T>): Iterator<T>

import { transform } from "itertools-ts";

const input = [1, 2, 3, 4, 5];

const result = transform.toIterator(input);
console.log(result.next !== undefined);
// true

Stream

Stream Sources

Of

Creates stream from an iterable.

Stream.of(data: Iterable<unknown>|Iterator<unknown>): Stream

import { Stream } from "itertools-ts";

const iterable = [1, 2, 3];

const result = Stream.of(iterable)
  .chainWith([4, 5, 6], [7, 8, 9])
  .zipEqualWith([1, 2, 3, 4, 5, 6, 7, 8, 9])
  .toArray();
// [[1, 1], [2, 2], [3, 3], [4, 4], [5, 5], [6, 6], [7, 7], [8, 8], [9, 9]]

Of Empty

Creates stream of nothing.

Stream.ofEmpty(): Stream

import { Stream } from "itertools-ts";

const result = Stream.ofEmpty()
  .chainWith([1, 2, 3])
  .toArray();
// 1, 2, 3

Stream Operations

Chain With

Return a stream chaining additional sources together into a single consecutive stream.

stream.chainWith(
  ...iterables: Array<Iterable<unknown>|Iterator<unknown>>
): Stream

import { Stream } from "itertools-ts";

const input = [1, 2, 3];

const result = Stream.of(input)
  .chainWith([4, 5, 6])
  .chainWith([7, 8, 9])
  .toArray();
// 1, 2, 3, 4, 5, 6, 7, 8, 9

Chunkwise

Return a stream consisting of chunks of elements from the stream.

stream.chunkwise(chunkSize: number): Stream

Chunk size must be at least 1.

import { Stream } from "itertools-ts";

const friends = ['Ross', 'Rachel', 'Chandler', 'Monica', 'Joey'];

const result = Stream.of(friends)
  .chunkwise(2)
  .toArray();
// ['Ross', 'Rachel'], ['Chandler', 'Monica'], ['Joey']

Chunkwise Overlap

Return a stream consisting of overlapping chunks of elements from the stream.

chunkwiseOverlap(
  chunkSize: number,
  overlapSize: number,
  includeIncompleteTail: boolean = true,
): Stream

Chunk size must be at least 1.
Overlap size must be less than chunk size.

import { Stream } from "itertools-ts";

const numbers = [1, 2, 3, 4, 5, 6, 7, 8, 9];

const result = Stream.of(numbers)
  .chunkwiseOverlap(3, 1)
  .toArray()
// [1, 2, 3], [3, 4, 5], [5, 6, 7], [7, 8, 9]

Distinct

Return a stream filtering out elements from the stream only returning distinct elements.

stream.distinct(): Stream

import { Stream } from "itertools-ts";

const input = [1, 2, 1, 2, 3, 3, '1', '1', '2', '3'];
const stream = Stream.of(input)
  .distinct()
  .toArray();
// 1, 2, 3, '1', '2', '3'

Enumerate

Enumerates elements of the stream.

stream.enumerate(): Stream

import { Stream } from "itertools-ts";

const input = ['a', 'b', 'c', 'd', 'e'];
const stream = Stream.of(input)
  .enumerate()
  .toArray();
// [[0, 'a'], [1, 'b'], [2, 'c'], [3, 'd'], [4, 'e']]

Filter

Filter out elements from the stream only keeping elements where there predicate function is true.

filter(predicate: (item: unknown) => boolean): Stream

import { Stream } from "itertools-ts";

const input = [1, -1, 2, -2, 3, -3];

const result = Stream.of(input)
  .filter((value) => value > 0)
  .toArray();
// 1, 2, 3

Flat Map

Map a function onto the elements of the stream and flatten the results.

stream.flatMap(mapper: (datum: unknown) => unknown): Stream

import { Stream } from "itertools-ts";

const data = [1, 2, 3, 4, 5];
const mapper = (item) => (item % 2 === 0) ? [item, item] : item;

const result = Stream.of(data)
  .flatMap(mapper)
  .toArray();
// [1, 2, 2, 3, 4, 4, 5]

Flatten

Flatten a multidimensional stream.

stream.flatten(dimensions: number = Infinity): Stream

import { Stream } from "itertools-ts";

const data = [1, [2, 3], [4, 5]];

const result = Stream.of(data)
  .flatten()
  .toArray();
// [1, 2, 3, 4, 5]

Keys

Iterate keys of key-value pairs.

keys(): Stream

import { Stream } from 'itertools-ts';

const dict = new Map([['a', 1], ['b', 2], ['c', 3]]);

const result = Stream.of(dict)
  .keys()
  .toArray();
// 'a', 'b', 'c'

Limit

Return a stream up to a limit.

Stops even if more data available if limit reached.

limit(count: number): Stream

import { Stream } from "itertools-ts";

const matrixMovies = ['The Matrix', 'The Matrix Reloaded', 'The Matrix Revolutions', 'The Matrix Resurrections'];
const limit = 1;

const goodMovies = Stream.of(matrixMovies)
  .limit(limit)
  .toArray();
// 'The Matrix' (and nothing else)

Map

Return a stream containing the result of mapping a function onto each element of the stream.

stream.map(mapper: (datum: unknown) => unknown): Stream

import { Stream } from "itertools-ts";

const grades = [100, 95, 98, 89, 100];

const result = Stream.of(grades)
  .map((grade) => grade === 100 ? 'A' : 'F')
  .toArray();
// A, F, F, F, A

Pairwise

Return a stream consisting of pairs of elements from the stream.

stream.pairwise(): Stream

Returns empty stream if given collection contains less than 2 elements.

import { Stream } from "itertools-ts";

const input = [1, 2, 3, 4, 5];

const stream = Stream.of(input)
  .pairwise()
  .toArray();
// [1, 2], [2, 3], [3, 4], [4, 5]

Slice

Extract a slice of the stream.

slice(start: number = 0, count?: number, step: number = 1): Stream

import { Stream } from "itertools-ts";

const olympics = [1992, 1994, 1996, 1998, 2000, 2002, 2004, 2006, 2008, 2010, 2012, 2014, 2016, 2018, 2020, 2022];

const summerOlympics = Stream.of(olympics)
  .slice(0, 8, 2)
  .toArray();
// [1992, 1996, 2000, 2004, 2008, 2012, 2016, 2020]

Values

Iterate keys of key-value pairs.

values(): Stream

import { Stream } from 'itertools-ts';

const dict = new Map([['a', 1], ['b', 2], ['c', 3]]);

const result = Stream.of(dict)
  .values()
  .toArray();
// 1, 2, 3

Zip With

Return a stream consisting of multiple iterable collections streamed simultaneously.

stream.zipWith(
  ...iterables: Array<Iterable<unknown>|Iterator<unknown>>
): Stream

For uneven lengths, iterations stops when the shortest iterable is exhausted.

import { Stream } from "itertools-ts";

const input = [1, 2, 3];

const stream = Stream.of(input)
  .zipWith([4, 5, 6])
  .toArray();
// [1, 4], [2, 5], [3, 6]

Zip Longest With

Return a stream consisting of multiple iterable collections streamed simultaneously.

stream.zipLongestWith(
  ...iterables: Array<Iterable<unknown>|Iterator<unknown>>
): Stream

Iteration continues until the longest iterable is exhausted.
For uneven lengths, the exhausted iterables will produce undefined for the remaining iterations.

import { Stream } from "itertools-ts";

const input = [1, 2, 3, 4, 5];

const stream = Stream.of(input)
  .zipLongestWith([4, 5, 6]);

for (const zipped of stream) {
  // [1, 4], [2, 5], [3, 6], [4, undefined], [5, undefined]
}

Zip Equal With

Return a stream consisting of multiple iterable collections of equal lengths streamed simultaneously.

zipEqualWith(
  ...iterables: Array<Iterable<unknown>|Iterator<unknown>>
): Stream

Works like Stream.zipWith() method but throws LengthException if lengths not equal, i.e., at least one iterator ends before the others.

import { Stream } from "itertools-ts";

const input = [1, 2, 3];

const stream = Stream.of(input)
  .zipEqualWith([4, 5, 6]);

for (const zipped of stream) {
    // [1, 4], [2, 5], [3, 6]
}

Terminal operations

Transformation Terminal Operations

To Array

Returns an array of stream elements.

stream.toArray(): Array<unknown>

import { Stream } from "itertools-ts";

const result = Stream.of([1, 2, 3, 4, 5])
  .map((x) => x**2)
  .toArray();
// [1, 4, 9, 16, 25]

Reduce Terminal Operations

To Count

Reduces iterable source to its length.

stream.toCount(): number

import { Stream } from "itertools-ts";

const input = [10, 20, 30, 40, 50];

const result = Stream.of(iterable)
  .toCount();
// 5

To Max

Reduces iterable source to its max value.

stream.toMax<TComparable>(compareBy?: (datum: unknown) => TComparable): unknown|undefined

Optional callable param compareBy must return comparable value.
If compareBy is not provided then items of given collection must be comparable.
Returns undefined if collection is empty.

import { Stream } from "itertools-ts";

const input = [1, -1, 2, -2, 3, -3];

const result = Stream.of(iterable)
  .toMax();
// 3

To Min

Reduces iterable source to its min value.

stream.toMin<TComparable>(compareBy?: (datum: unknown) => TComparable): unknown|undefined

Optional callable param compareBy must return comparable value.
If compareBy is not provided then items of given collection must be comparable.
Returns undefined if collection is empty.

import { Stream } from "itertools-ts";

const input = [1, -1, 2, -2, 3, -3];

const result = Stream.of(iterable)
  .toMin();
// -3

To Product

Reduces iterable source to the product of its items.

stream.toProduct(): number|undefined

Returns undefined if stream is empty.

import { Stream } from "itertools-ts";

const input = [1, 2, 3, 4, 5];

const result = Stream.of(input)
  .toProduct();
// 120

To Sum

Reduces iterable source to the sum of its items.

stream.toSum(): number

import { Stream } from "itertools-ts";

const input = [1, 2, 3, 4, 5];

const result = Stream.of(iterable)
  .toSum();
// 15

To Value

Reduces iterable source like array_reduce() function.

toValue<T>(
  reducer: (carry: T|undefined, datum: unknown) => T,
  initialValue?: T,
): T|undefined

import { Stream } from "itertools-ts";

const input = [1, 2, 3, 4, 5];

const result = Stream.of(input)
  .toValue((carry, item) => carry + item);
// 15

Unit testing

npm i
npm run test

License

IterTools TS is licensed under the MIT License.