IterTools for TypeScript and JavaScript

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
• Pipe 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
}

// Async example
const letters = ['a', 'b'].map((x) => Promise.resolve(x));
const numbers = [1, 2].map((x) => Promise.resolve(x));

for await (const [letter, number] of multi.zipAsync(letters, numbers)) {
  console.log(`${letter}${number}`);  // a1, b2
}

Stream Iteration Tools Example

import { Stream, AsyncStream } from 'itertools-ts';

const result1 = 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

// Async example
const result2 = await AsyncStream.of([1, 1, 2, 2, 3, 4, 5].map((x) => Promise.resolve(x)))
  .distinct()             // [1, 2, 3, 4, 5]
  .map((x) => x**2)       // [1, 4, 9, 16, 25]
  .filter((x) => x < 10)  // [1, 4, 9]
  .toSum();               // 14

More about Streams

Pipe Iteration Tools Example

import { createPipe } from 'itertools-ts';

const pipe = createPipe(
  set.distinct<number>,
  (input) => single.map(input, (x) => x**2),
  (input) => single.filter(input, (x) => x < 10),
  reduce.toSum,
);
const result1 = pipe([1, 1, 2, 2, 3, 4, 5]); // 14
const result2 = pipe([1, 1, 1, 2, 2, 2]);    // 5

// Async example
const asyncPipe = createPipe(
  set.distinctAsync<number>,
  (input) => single.mapAsync(input, (x) => x**2),
  (input) => single.filterAsync(input, (x) => x < 10),
  reduce.toSumAsync,
);
const result3 = await asyncPipe([1, 1, 2, 2, 3, 4, 5].map((x) => Promise.resolve(x))); // 14
const result4 = await asyncPipe([1, 1, 1, 2, 2, 2].map((x) => Promise.resolve(x)));    // 5

// Another way to create pipes
const anotherPipe = createPipe()
  .add(set.distinct<number>)
  .add((input) => single.map(input, (x) => x**2))
  .add((input) => single.filter(input, (x) => x < 10))
  .add(reduce.toSum);

const result5 = anotherPipe([1, 1, 2, 2, 3, 4, 5]); // 14
const result6 = anotherPipe([1, 1, 1, 2, 2, 2]);    // 5

More about Pipes

All functions work on iterable collections and iterators:

• Array
• Set
• Map
• String
• Generator
• Iterable
• Iterator

Every function have an analog with "Async"-suffixed name for working with async iterable and iterators (e.g. zip and zipAsync):

• AsyncIterable
• AsyncIterator

If an asynchronous function takes other functions as input, they can also be asynchronous.

import { single } from 'itertools-ts';

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

for await (const goodMovie of single.filterAsync(
  starWarsEpisodes,
  async (episode) => {
    return Promise.resolve(episode > 3 && episode < 8);
  }
)) {
  console.log(goodMovie);
}
// 4, 5, 6, 7

Setup

npm i itertools-ts

Quick Reference

Loop Iteration Tools

Multi Iteration

Single Iteration

Infinite Iteration

Math Iteration

Reduce

Set and multiset Iteration

Combinatorics

Summary

Transform

Stream and AsyncStream Iteration Tools

Stream Sources

Stream Operations

Stream Terminal Operations

Transformation Terminal Operations

Reduction Terminal Operations

Summary Terminal Operations

Stream Debug Operations

Usage

Multi Iteration

Chain

Chain multiple iterables together into a single continuous sequence.

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

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<T extends Array<Iterable<unknown> | Iterator<unknown>>>(
  ...iterables: T
): Iterable<ZipTuple<T, never>>

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 Filled

Iterate multiple iterable collections simultaneously.

function* zipFilled<T extends Array<Iterable<unknown> | Iterator<unknown>>, F>(
  filler: F,
  ...iterables: T
): Iterable<ZipTuple<T, F>>

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

import { multi } from 'itertools-ts';

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

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

Zip Longest

Iterate multiple iterable collections simultaneously.

function* zipLongest<T extends Array<Iterable<unknown> | Iterator<unknown>>>(
  ...iterables: T
): Iterable<ZipTuple<T, undefined>>

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<T extends Array<Iterable<unknown> | Iterator<unknown>>>(
  ...iterables: T
): Iterable<ZipTuple<T, never>>

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]
}

Compress

Compress an iterable by filtering out data that is not selected.

function* compress<T>(
  data: Iterable<T> | Iterator<T>,
  selectors: Iterable<number|boolean> | Iterator<number|boolean>
): Iterable<T>

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 goodMovies = [0, 0, 0, 1, 1, 1, 1, 0, 0];

for (const goodMovie of single.compress(movies, goodMovies)) {
  console.log(goodMovie);
}
// 'A New Hope', 'Empire Strikes Back', 'Return of the Jedi', 'The Force Awakens'

Drop While

Drop elements from the iterable while the predicate function is true.

Once the predicate function returns false once, all remaining elements are returned.

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

import { single } from 'itertools-ts';

const scores    = [50, 60, 70, 85, 65, 90];
const predicate = (x) => x < 70;

for (const score of single.dropWhile(scores, predicate)) {
  console.log(score);
}
// 70, 85, 65, 90

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]

Group By

Group data by a common data element.

Iterate pairs of group name and collection of grouped items.

export function* groupBy<
  T,
  TItemKeyFunction extends ((item: T) => string) | undefined,
  TResultItem extends TItemKeyFunction extends undefined ? [string, Array<T>] : [string, Record<string, T>]
>(
  data: Iterable<T> | Iterator<T>,
  groupKeyFunction: (item: T) => string,
  itemKeyFunction?: TItemKeyFunction
): Iterable<TResultItem>

• The groupKeyFunction determines the key to group elements by.
• The optional itemKeyFunction allows custom indexes within each group member.
• Collection of grouped items may be an array or an object (depends on presence of itemKeyFunction param).

import { single } from 'itertools-ts';

const cartoonCharacters = [
    ['Garfield', 'cat'],
    ['Tom', 'cat'],
    ['Felix', 'cat'],
    ['Heathcliff', 'cat'],
    ['Snoopy', 'dog'],
    ['Scooby-Doo', 'dog'],
    ['Odie', 'dog'],
    ['Donald', 'duck'],
    ['Daffy', 'duck'],
];

const charactersGroupedByAnimal = {};
for (const [animal, characters] of single.groupBy(cartoonCharacters, (x) => x[1])) {
    charactersGroupedByAnimal[animal] = characters;
}
/*
{
  cat: [
    ['Garfield', 'cat'],
    ['Tom', 'cat'],
    ['Felix', 'cat'],
    ['Heathcliff', 'cat'],
  ],
  dog: [
    ['Snoopy', 'dog'],
    ['Scooby-Doo', 'dog'],
    ['Odie', 'dog'],
  ],
  duck: [
    ['Donald', 'duck'],
    ['Daffy', 'duck'],
  ],
}
*/

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'

Skip

Skip n elements in the iterable after optional offset offset.

function* skip<T>(
  data: Iterable<T> | Iterator<T>,
  count: number,
  offset: number = 0
): Iterable<T>

import { single } from 'itertools-ts';

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

const prequelsRemoved = [];
for (const nonPrequel of Single.skip(movies, 3)) {
  prequelsRemoved.push(nonPrequel);
} // Episodes IV - IX

const onlyTheBest = [];
for (const nonSequel of Single.skip(prequelsRemoved, 3, 3)) {
  onlyTheBest.push(nonSequel);
}
// 'A New Hope', 'The Empire Strikes Back', 'Return of the Jedi'

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]

Sort

Iterate the collection sorted.

function* sort<T>(
  data: Iterable<T> | Iterator<T>,
  comparator?: Comparator<T>,
): Iterable<T>

Uses default sorting if optional comparator function not provided.

import { single } from 'itertools-ts';

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

for (const datum of single.sort(data)) {
  console.log(datum);
}
// 1, 2, 3, 4, 5, 6, 7, 8, 9

Take While

Return elements from the iterable as long as the predicate is true.

Stops iteration as soon as the predicate returns false, even if other elements later on would eventually return true (different from filterTrue).

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

import { single } from 'itertools-ts';

const prices = [0, 0, 5, 10, 0, 0, 9];
const isFree = (price) => price == 0;

for (const freePrice of single.takeWhile(prices, isFree)) {
  console.log(freePrice);
}
// 0, 0

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

Infinite Iteration

Count

Count sequentially forever.

function* count(start: number = 1, step: number = 1): Iterable<number>

import { infinite } from 'itertools-ts';

for (const i of infinite.count()) {
  console.log(i);
}
// 1, 2, 3, 4, 5, ...

Cycle

Cycle through the elements of a collection sequentially forever.

function* cycle<T>(iterable: Iterable<T> | Iterator<T>): Iterable<T>

import { infinite } from 'itertools-ts';

for (const item of infinite.cycle(['rock', 'paper', 'scissors'])) {
  console.log(item);
}
// 'rock', 'paper', 'scissors', 'rock', 'paper', 'scissors', 'rock', ...

Repeat

Repeat an item forever.

function* repeat<T>(item: T): Iterable<T>

import { infinite } from 'itertools-ts';

for (const item of infinite.repeat('bla')) {
  console.log(item);
}
// bla, bla, bla, bla, bla, ...

Math Iteration

Running Average

Accumulate the running average over a list of numbers.

function* runningAverage(
  numbers: Iterable<Numeric> | Iterator<Numeric>,
  initialValue?: number
): Iterable<number>

import { math } from 'itertools-ts';

const grades = [100, 80, 80, 90, 85];

for (const runningAverage of math.runningAverage(grades)) {
  console.log(runningAverage);
}
// 100, 90, 86.667, 87.5, 87

Running Difference

Accumulate the running difference over a list of numbers.

function* runningDifference(
  numbers: Iterable<Numeric> | Iterator<Numeric>,
  initialValue?: number
): Iterable<number>

import { math } from 'itertools-ts';

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

for (const runningDifference of math.runningDifference(credits)) {
    console.log(runningDifference);
}
// -1, -3, -6, -10, -15

Provide an optional initial value to lead off the running difference.

import { math } from 'itertools-ts';

const dartsScores   = [50, 50, 25, 50];
const startingScore = 501;

for (const runningScore of math.runningDifference(dartsScores, startingScore)) {
  console.log(runningScore);
}
// 501, 451, 401, 376, 326

Running Max

Accumulate the running maximum over a list of numbers.

function* runningMax(
  numbers: Iterable<Numeric> | Iterator<Numeric>,
  initialValue?: number
): Iterable<number>

import { math } from 'itertools-ts';

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

for (const runningMax of math.runningMax(numbers)) {
  console.log(runningMax);
}
// 1, 2, 2, 3, 5

Running Min

Accumulate the running minimum over a list of numbers.

function* runningMin(
  numbers: Iterable<Numeric> | Iterator<Numeric>,
  initialValue?: number
): Iterable<number>

import { math } from 'itertools-ts';

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

for (const runningMin of math.runningMin(numbers)) {
    console.log(runningMin);
}
// 3, 3, 2, 2, 1

Running Product

Accumulate the running product over a list of numbers.

function* runningProduct(
  numbers: Iterable<Numeric> | Iterator<Numeric>,
  initialValue?: number
): Iterable<number>

import { math } from 'itertools-ts';

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

for (const runningProduct of math.runningProduct(numbers)) {
  console.log(runningProduct);
}
// 1, 2, 6, 24, 120

Provide an optional initial value to lead off the running product.

import { math } from 'itertools-ts';

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

for (const runningProduct of math.runningProduct(numbers, initialValue)) {
  console.log(runningProduct);
}
// 5, 5, 10, 30, 120, 600

Running Total

Accumulate the running total over a list of numbers.

function* runningTotal(
  numbers: Iterable<Numeric> | Iterator<Numeric>,
  initialValue?: number
): Iterable<number>

import { math } from 'itertools-ts';

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

for (const runningTotal of math.runningTotal(prices)) {
    console.log(runningTotal);
}
// 1, 3, 6, 10, 15

Provide an optional initial value to lead off the running total.

import { math } from 'itertools-ts';

const prices = [1, 2, 3, 4, 5];
const initialValue = 5;

for (const runningTotal of math.runningTotal(prices, initialValue)) {
  console.log(runningTotal);
}
// 5, 6, 8, 11, 15, 20

Reduce

To Average

Reduces to the mean average.

Returns undefined if collection is empty.

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

import { reduce } from 'itertools-ts';

const grades = [100, 90, 95, 85, 94];

const finalGrade = reduce.toAverage(numbers);
// 92.8

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 First

Reduces iterable to its first element.

function toFirst<T>(data: Iterable<T> | Iterator<T>): T

Throws LengthException if collection is empty.

import { reduce } from 'itertools-ts';

const medals = ['gold', 'silver', 'bronze'];

const first = reduce.toFirst(medals);
// gold

To First And Last

Reduces iterable to its first and last elements.

function toFirstAndLast<T>(data: Iterable<T> | Iterator<T>): [T, T]

Throws LengthException if collection is empty.

import { reduce } from 'itertools-ts';

const medals = ['gold', 'silver', 'bronze'];

const result = reduce.toFirstAndLast(medals);
// [gold, bronze]

To Last

Reduces iterable to its last element.

function toLast<T>(data: Iterable<T> | Iterator<T>): T

Throws LengthException if collection is empty.

import { reduce } from 'itertools-ts';

const medals = ['gold', 'silver', 'bronze'];

const first = reduce.toFirst(medals);
// bronze

To Max

Reduces to the max value.

function toMax<TValue>(
  data: Iterable<TValue>|Iterator<TValue>,
  compareBy?: (datum: TValue) => Comparable,
): 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>(
  data: Iterable<TValue>|Iterator<TValue>,
  compareBy?: (datum: TValue) => Comparable,
): 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 Min Max

Reduces collection to its lower and upper bounds.

function toMinMax<T>(
  data: Iterable<T> | Iterator<T>,
  compareBy?: (item: T) => Comparable
): [T?, T?]

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

import { reduce } from 'itertools-ts';

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

const result = reduce.toMinMax(numbers);
// [1, 5]

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,
// },
// {
//   title: 'The Matrix',
//   rating: 4.7,
// }]

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 Range

Reduces given collection to its range (difference between max and min).

function toRange(numbers: Iterable<Numeric> | Iterator<Numeric>): number

Returns 0 if iterable source is empty.

import { reduce } from 'itertools-ts';

const grades = [100, 90, 80, 85, 95];

const range = reduce.toRange(numbers);
// 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, datum: TInput) => TOutput,
  initialValue?: TOutput
): TOutput

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>,
  compareBy?: (datum: T) => Comparable
): Iterable<T>

Always treats different instances of objects and arrays as unequal.

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


const users = [
  { 'name': 'John', 'id': 1 },
  { 'name': 'Mary', 'id': 2 },
  { 'name': 'Mary', 'id': 3 },
  { 'name': 'John', 'id': 4 },
  { 'name': 'Jane', 'id': 5 },
];

for (const user of set.distinct(users, (item) => item['name'])) {
  console.log(user);
}
// { 'name': 'John', 'id': 1 }, { 'name': 'Mary', 'id': 2 }, { 'name': 'Jane', 'id': 5 }

Intersection

Iterates intersection of iterables.

function* intersection<T>(...iterables: Array<Iterable<T> | Iterator<T>>): Iterable<T>

• Always treats different instances of objects and arrays as unequal.
• If input iterables produce duplicate items, then multiset intersection rules apply.

import { set } from 'itertools-ts';

const chessPieces = ['rook', 'knight', 'bishop', 'queen', 'king', 'pawn'];
const shogiPieces = ['rook', 'knight', 'bishop', 'king', 'pawn', 'lance', 'gold general', 'silver general'];

for (const commonPiece of set.intersection(chessPieces, shogiPieces)) {
    console.log(commonPiece);
}
// rook, knight, bishop, king, pawn

Partial Intersection

Iterates M-partial intersection of iterables.

function* partialIntersection<T>(
  minIntersectionCount: number,
  ...iterables: Array<Iterable<T> | Iterator<T>>
): Iterable<T>

• Always treats different instances of objects and arrays as unequal.
• If input iterables produce duplicate items, then multiset intersection rules apply.

import { set } from 'itertools-ts';

const staticallyTyped    = ['c++', 'java', 'c#', 'go', 'haskell'];
const dynamicallyTyped   = ['php', 'python', 'javascript', 'typescript'];
const supportsInterfaces = ['php', 'java', 'c#', 'typescript'];

for (const language of set.partialIntersection(2, staticallyTyped, dynamicallyTyped, supportsInterfaces)) {
  console.log(language);
}
// c++, java, c#, go, php

Symmetric difference

Iterates the symmetric difference of iterables.

function* symmetricDifference<T>(
  ...iterables: Array<Iterable<T> | Iterator<T>>
): Iterable<T>

• Always treats different instances of objects and arrays as unequal.
• If input iterables produce duplicate items, then multiset difference rules apply.

import { set } from 'itertools-ts';

const a = [2, 3, 4, 7];
const b = [2, 3, 5, 8];
const c = [2, 3, 6, 9];

for (const item of set.symmetricDifference(a, b, c)) {
  console.log(item);
}
// 4, 5, 6, 7, 8, 9

Union

Iterates the union of iterables.

function* union<T>(...iterables: Array<Iterable<T> | Iterator<T>>): Iterable<T>

• Always treats different instances of objects and arrays as unequal.
• If input iterables produce duplicate items, then multiset difference rules apply.

import { set } from 'itertools-ts';

const a = [1, 2, 3];
const b = [2, 3, 4];
const c = [3, 4, 5];

for (const item of set.symmetricDifference(a, b, c)) {
    console.log(item);
}
// 1, 2, 3, 4, 5

Combinatorics

Cartesian Product

Iterates cartesian product of given iterables.

function* cartesianProduct<T extends Array<Iterable<unknown> | Iterator<unknown>>>(
  ...iterables: T
): Iterable<ZipTuple<T, never>>

import { combinatorics } from 'itertools-ts';

const numbers = [1, 2];
const letters = ['a', 'b'];
const chars = ['!', '?'];

for (const tuple of combinatorics.cartesianProduct(numbers, letters, chars)) {
  console.log(tuple);
}
/*
  [1, 'a', '!'],
  [1, 'a', '?'],
  [1, 'b', '!'],
  [1, 'b', '?'],
  [2, 'a', '!'],
  [2, 'a', '?'],
  [2, 'b', '!'],
  [2, 'b', '?'],
*/

Combinations

Iterates all combinations of given iterable.

function* combinations<T>(
  data: Iterable<T> | Iterator<T>,
  length: number
): Iterable<Array<T>>

```typescript import { combinatorics } from 'itertools-ts';

const fruits = ['apple', 'banana', 'cherry'];

for (const combination of combinatorics.combinations(fruits, 2)) { c

IterTools Typescript Change Log

v2.2.0 - 2025-01-31

New features

• combinatorics
  • combinations()
  • combinationsAsync()
• Stream
  • combinations()
• AsyncStream
  • combinations()

v2.1.0 - 2025-01-29

New features

• combinatorics
  • permutations()
  • permutationsAsync()
  • cartesianProduct()
  • cartesianProductAsync()
• Stream
  • permutations()
• AsyncStream
  • permutations()

Improvements

• toArray() function optimized.

Deprecations

• set
  • cartesianProduct() (use combinatorics.cartesianProduct() instead).
  • cartesianProductAsync() (use combinatorics.cartesianProductAsync() instead).

v2.0.0 - 2025-01-25

Improvements

• Stream and AsyncStream are fully refactored
  • Classes made generic.
  • All the methods made generic and save the typing.
• reduce
  • toValue(), toValueAsync() — union return type has been replaced by inferred type.
  • toRange(), toRangeAsync() — use Numeric type in arguments.
• multi
  • Type ZipTuple — added support for iterators and async iterables / iterators.
• math
  • All the methods use Numeric type in arguments.
• All the tests are refactored to check the typing.
• Found bugs fixed.

New features

• types
  • Numeric
  • NumericString

v1.29.1 - 2025-01-23

Improvements

• single
  • groupBy() — union return type has been replaced by inferred type.
  • groupByAsync() — union return type has been replaced by inferred type.

v1.29.0 - 2024-12-24

New features

• Pipe
  • add()

v1.28.1 - 2024-12-23

Documentation fixed.

v1.28.0 - 2024-12-22

New features

• createPipe()

v1.27.1 - 2024-03-03

Package Size Optimization.

v1.27.0 - 2023-11-13

New features

• set
  • cartesianProduct()
  • cartesianProductAsync()
• Stream
  • cartesianProductWith()
• AsyncStream
  • cartesianProductWith()

v1.26.0 - 2023-11-12

New features

• infinite
  • cycle()
  • cycleAsync()
• Stream
  • ofCycle()
• AsyncStream
  • ofCycle()

v1.25.0 - 2023-11-02

New features

• infinite
  • repeat()
• Stream
  • ofRepeat()
• AsyncStream
  • ofRepeat()

v1.24.0 - 2023-10-23

New features

• summary
  • toRange()
  • toRangeAsync()
• infinite
  • count()
• Stream
  • toRange()
  • ofCount()
• AsyncStream
  • toRange()
  • ofCount()

v1.23.0 - 2023-05-25

New features

• summary
  • exactlyN()
  • exactlyNAsync()
• Stream
  • exactlyN()
• AsyncStream
  • exactlyN()

v1.22.0 - 2023-04-20

New features

• math
  • runningAverage()
  • runningAverageAsync()
• Stream
  • runningAverage()
• AsyncStream
  • runningAverage()

v1.21.0 - 2023-04-18

Improvements

• set
  • distinct() supports optional comparable getter param.

v1.20.0 - 2023-04-15

New features

• math
  • runningDifference()
  • runningDifferenceAsync()
  • runningMax()
  • runningMin()
  • runningMinAsync()
  • runningMaxAsync()
  • runningProduct()
  • runningProductAsync()
• Stream
  • runningDifference()
  • runningMax()
  • runningMin()
  • runningProduct()
• AsyncStream
  • runningDifference()
  • runningMax()
  • runningMin()
  • runningProduct()

v1.19.0 - 2023-04-08

New features

• Single
  • sort()
  • sortAsync()
• Stream
  • peek()
  • peekStream()
  • sort()
• AsyncStream
  • peek()
  • peekStream()
  • sort()
• types
  • Comparator

v1.18.0 - 2023-04-02

New features

• transform
  • teeAsync()
• Stream
  • tee()
• AsyncStream
  • tee()
• types
  • ZipTuple

Improvements

• multi
  • all the zip function's interfaces are simplified

v1.17.0 - 2023-04-02

New features

• transform
  • tee()

Bug fix

• multi.zipEqual() — return type fixed

Improvements

• Minor documentation changes

v1.16.0 - 2023-04-01

New features

• multi
  • chainAsync()
  • zipAsync()
  • zipFilledAsync()
  • zipLongestAsync()
  • zipEqualAsync()
• single
  • chunkwiseAsync()
  • chunkwiseOverlapAsync()
  • compressAsync()
  • dropWhileAsync()
  • enumerateAsync()
  • filterAsync()
  • flatMapAsync()
  • flattenAsync()
  • groupByAsync()
  • keysAsync()
  • limitAsync()
  • mapAsync()
  • pairwiseAsync()
  • repeatAsync()
  • sliceAsync()
  • skipAsync()
  • takeWhileAsync()
  • valuesAsync()
• set
  • distinctAsync()
  • intersectionAsync()
  • partialIntersectionAsync()
  • symmetricDifferenceAsync()
  • unionAsync()
• reduce
  • toValueAsync()
  • toAverageAsync()
  • toCountAsync()
  • toFirstAsync()
  • toFirstAndLastAsync()
  • toLastAsync()
  • toMaxAsync()
  • toMinAsync()
  • toMinMaxAsync()
  • toProductAsync()
  • toSumAsync()
• summary
  • isAsyncIterable()
  • allMatchAsync()
  • allUniqueAsync()
  • anyMatchAsync()
  • isEmptyAsync()
  • isReversedAsync()
  • isSortedAsync()
  • noneMatchAsync()
  • sameAsync()
  • sameCountAsync()
• transform
  • toArrayAsync()
  • toAsyncIterable()
  • toAsyncIterator()
  • toMapAsync()
  • toSetAsync()
• math
  • runningTotalAsync()
• AsyncStream
  • of
  • ofEmpty
  • zipWith
  • zipFilledWith
  • zipLongestWith
  • zipEqualWith
  • chainWith
  • chunkwiseOverlap
  • chunkwise
  • compress
  • dropWhile
  • filter
  • enumerate
  • keys
  • limit
  • map
  • flatMap
  • flatten
  • groupBy
  • pairwise
  • runningTotal
  • skip
  • slice
  • takeWhile
  • values
  • distinct
  • intersectionWith
  • partialIntersectionWith
  • symmetricDifferenceWith
  • unionWith
  • toValue
  • toAverage
  • toCount
  • toMax
  • toMin
  • toMinMax
  • toFirst
  • toFirstAndLast
  • toLast
  • toSum
  • toProduct
  • allMatch
  • allUnique
  • anyMatch
  • isSorted
  • isReversed
  • noneMatch
  • sameWith
  • sameCountWith
  • toArray
  • toMap
  • toSet

v1.15.0 - 2023-03-30

Improvements

• multi
  • all function interfaces are clarified

v1.14.0 - 2023-03-28

New Features

• single
  • skip()
• Stream
  • skip()

v1.13.0 - 2023-03-21

New Features

• single
  • dropWhile()
  • takeWhile()
  • compress()
• Stream
  • dropWhile()
  • takeWhile()
  • compress()

v1.12.0 - 2023-03-21

New Features

• transform
  • toMap()
  • toSet()
• Stream
  • toMap()
  • toSet()
• types
  • RecordKey

Improvements

• transform.toIterable() now can also accept records as input.

v1.11.0 - 2023-03-20

New Features

• reduce
  • toFirstAndLast()
  • toMinMax()
• Stream
  • toFirstAndLast()
  • toMinMax()

Improvements

• reduce.toMin() and reduce.toMax() functions are refactored using Comparable type.

v1.10.0 - 2023-03-19

New Features

• multi
  • zipFilled()
• Stream
  • zipFilledWith()

v1.9.0 - 2023-03-17

New Features

• summary
  • allUnique()
  • isSorted()
  • isReversed()
• Stream
  • allUnique()
  • isSorted()
  • isReversed()
• types
  • Comparable

v1.8.0 - 2023-03-16

New Features

• summary
  • allMatch()
  • anyMatch()
  • noneMatch()
• Stream
  • allMatch()
  • anyMatch()
  • noneMatch()

v1.7.0 - 2023-03-15

New Features

• summary
  • sameCount()
• Stream
  • sameCountWith()

Improvements

• Type annotations added to tests (to repair github workflow).

v1.6.1 - 2023-03-14

Improvements

• Reduced package size by including fewer tests.

v1.6.0 - 2023-03-14

New Features

• summary
  • same()
• Stream
  • sameWith()

v1.5.0 - 2023-03-13

New Features

• single
  • groupBy()
• summary
  • isString()
• Stream
  • groupBy()

v1.4.0 - 2023-03-13

New Features

• set
  • intersection()
  • partialIntersection()
  • symmetricDifference()
  • union()
• Stream
  • intersectionWith()
  • partialIntersectionWith()
  • symmetricDifferenceWith()
  • unionWith()

v1.3.0 - 2023-03-12

New Features

• math
  • runningTotal()
• Stream
  • runningTotal()

v1.2.0 - 2023-03-11

New Features

• reduce
  • toFirst()
  • toLast()
• Stream
  • toFirst()
  • toLast()

v1.1.0 - 2023-03-11

New Features

• reduce
  • toAverage()
• Stream
  • toAverage()

v1.0.0 - 2023-03-11

Initial release.