@flowr/iterator

Type-safe utilities for iterating through Lists, Arrays, and Sets.

Installation

You can use the following command to install this package, or replace pnpm add with your package manager of choice.

pnpm add -D @flowr/iterator

Usage

For any of the following examples, you can import the utilities from the index file:

import { append } from '@flowr/iterator';
const { append } = require('@flowr/iterator');

Or you can import the utilities directly:

import { append } from '@flowr/iterator/append';
const { append } = require('@flowr/iterator/append');

append

Appends iterables to the end of the first iterable, returning a new iterable combining all of them. It's similar to concatenating arrays or doing [...a, ...b, ...c].

const iterable = append([1, 2, 3], [4, 5, 6], [7, 8, 9]);
console.log([...iterable]);
// Output: [1, 2, 3, 4, 5, 6, 7, 8, 9]

at

Advances the iterable to the nth element and returns it. If the iterable is exhausted before reaching the nth element, it returns undefined.

const iterable = [1, 2, 3, 4, 5];
console.log(at(iterable, 2));
// Output: 3

average

Consumes the iterable and returns the average value of all the elements. If the iterable is empty, it returns null.

const iterable = [1, 2, 3, 4, 5];
console.log(average(iterable));
// Output: 3

chain

Similar to append, but takes an iterable of iterables and chains them together.

const iterable = chain([1, 2, 3], [4, 5, 6], [7, 8, 9]);
console.log([...iterable]);
// Output: [1, 2, 3, 4, 5, 6, 7, 8, 9]

chunk

Chunks the iterable into arrays of at most size elements.

const iterable = [1, 2, 3, 4, 5];
console.log([...chunk(iterable, 2)]);
// Output: [[1, 2], [3, 4], [5]]

compact

Creates a new iterable that yields all the non-nullish values (null and undefined) from the iterable.

const iterable = [1, null, 2, undefined, 3];
console.log([...compact(iterable)]);
// Output: [1, 2, 3]

compress

Creates a new iterable of the first iterable based on the truthiness of the corresponding element in the second iterable.

const iterable = compress([1, 2, 3, 4, 5], [true, false, true, false, true]);
console.log([...iterable]);
// Output: [1, 3, 5]

contains

Advances the iterable until it finds the element, returning true if it's found and false otherwise.

const iterable = [1, 2, 3, 4, 5];
console.log(contains(iterable, 3));
// Output: true

count

Consumes the iterable and returns the number of elements.

const iterable = [1, 2, 3, 4, 5];
console.log(count(iterable));
// Output: 5

cycle

Creates an infinite iterable by cycling through the elements of the input iterable.

const iterable = cycle([1, 2, 3]);
for (const element of iterable)
	console.log(element);
	// Output: 1, 2, 3, 1, 2, 3, 1, 2, 3, ...

difference

Creates an iterable with the elements of the first iterable that are not in the second iterable.

const first = [1, 2, 3, 4, 5];
const second = [3, 4, 5, 6, 7];
console.log([...difference(first, second)]);
// Output: [1, 2]

drop

Advances the iterable by count elements from the iterable.

const iterable = drop(iterator, 2);
console.log([...iterable]);
// Output: [3, 4, 5]

dropLast

Consumes the iterable, creating a new iterator without the last count elements from the iterable.

const iterable = dropLast([1, 2, 3, 4, 5], 2);
console.log([...iterable]);
// Output: [1, 2, 3]

dropWhile

Creates a new iterator without the elements that satisfy the specified test.

const iterable = dropWhile([1, 2, 3, 4, 5], value => value < 3);
console.log([...iterable]);
// Output: [3, 4, 5]

empty

Creates an empty iterator.

const iterable = empty();
console.log([...iterable]);
// Output: []

enumerate

Creates a new iterable that yields the index and value of each element.

const iterable = ['a', 'b', 'c'];
for (const [index, value] of enumerate(iterable))
	console.log(`Index: ${index}, Value: ${value}`);
	// Output: Index: 0, Value: a
	// Output: Index: 1, Value: b
	// Output: Index: 2, Value: c

every

Tests whether all elements in the iterable pass the test implemented by the provided function.

const iterable = [1, 2, 3, 4, 5];
console.log(every(iterable, value => value < 10));
// Output: true
console.log(every(iterable, value => value < 3));
// Output: false

filter

Creates an iterable with the elements that pass the test implemented by the provided function.

const iterable = [1, 2, 3, 4, 5];
console.log([...filter(iterable, value => value % 2 === 0)]);
// Output: [2, 4]

find

Advances the iterable until it finds the element, returning it if it's found and undefined otherwise.

const iterable = [1, 2, 3, 4, 5];
console.log(find(iterable, value => value % 2 === 0));
// Output: 2

findIndex

Advances the iterable until it finds the element, returning its index if it's found and -1 otherwise.

const iterable = [1, 2, 3, 4, 5];
console.log(findIndex(iterable, value => value % 2 === 0));
// Output: 1

first

Consumes the first element of the iterable, returning it if it's found and undefined otherwise.

const iterable = [1, 2, 3, 4, 5];
console.log(first(iterable));
// Output: 1

flat

Creates an iterable that yields the elements of each iterable in the input iterable.

const iterable = flat([
	[1, 2],
	[3, 4],
	[5, 6]
]);
console.log([...iterable]);
// Output: [1, 2, 3, 4, 5, 6]

flatMap

Creates an iterable that yields the elements of each iterable returned by the provided function on each element of the input iterable.

const iterable = [1, 2, 3];
console.log([...flatMap(iterable, value => [value, value * 2])]);
// Output: [1, 2, 2, 4, 3, 6]

forEach

Executes a provided function once for each iterable element.

const iterable = [1, 2, 3, 4, 5];
forEach(iterable, value => console.log(value));
// Output: 1, 2, 3, 4, 5

from

Resolves an iterable from an iterable or iterator-like object.

const iterable = from([1, 2, 3, 4, 5]);
for (const element of iterable)
	console.log(element);
	// Output: 1, 2, 3, 4, 5

indexOf

Advances the iterable until it finds the element, returning its index if it's found and -1 otherwise.

const iterable = [1, 2, 3, 4, 5];
console.log(indexOf(iterable, 3));
// Output: 2

intersect

Creates an iterable with the elements that are in both input iterables.

const iterable = intersect([1, 2, 3, 4, 5], [3, 4, 5, 6, 7]);
console.log([...iterable]);
// Output: [3, 4, 5]

isEmpty

Advances the iterable once, returning true if it's exhausted and false otherwise.

console.log(isEmpty([]));
// Output: true

console.log(isEmpty([1, 2, 3, 4, 5]));
// Output: false

last

Consumes the iterable until it's exhausted, returning the last element.

const iterable = [1, 2, 3, 4, 5];
console.log(last(iterable));
// Output: 5

map

Creates an iterable with the results of calling a provided function on each element.

const iterable = [1, 2, 3, 4, 5];
console.log([...map(iterable, value => value * 2)]);
// Output: [2, 4, 6, 8, 10]

max

Consumes the iterable and returns the highest number element. If the iterable is empty, or contains only non-number values, it returns null.

const iterable = [1, 2, 3, 4, 5];
console.log(max(iterable));
// Output: 5

min

Consumes the iterable and returns the lowest number element. If the iterable is empty, or contains only non-number values, it returns null.

const iterable = [1, 2, 3, 4, 5];
console.log(min(iterable));
// Output: 1

partition

Consumes the iterable and creates two arrays, one with the elements that pass the test and another with the elements that don't.

const iterable = [1, 2, 3, 4, 5];
const [even, odd] = partition(iterable, value => value % 2 === 0);

console.log(even);
// Output: [2, 4]

console.log(odd);
// Output: [1, 3, 5]

peekable

Creates an iterator that allows you to peek at the next element without advancing the iterator.

const iterable = [1, 2, 3, 4, 5];
const peekableIterator = peekable(iterable);

console.log(peekableIterator.next());
// Output: { value: 1, done: false }

console.log(peekableIterator.peek());
// Output: { value: 2, done: false }

console.log(peekableIterator.next());
// Output: { value: 2, done: false }

console.log(peekableIterator.next());
// Output: { value: 3, done: false }

prepend

Creates an iterator with the provided iterables prepended to the first iterable.

console.log([...prepend([3, 4, 5], [1], [2])]);
// Output: [1, 2, 3, 4, 5]

product

Consumes the iterable and returns the product of all the elements. If the iterable is empty, it returns 1.

const iterable = [1, 2, 3, 4, 5];
console.log(product(iterable));
// Output: 120

range

Creates an iterable with the numbers from start to stop (exclusive) with an optional step.

const iterable = range(0, 5);
console.log([...iterable]);
// Output: [0, 1, 2, 3, 4]

If start is greater than stop, the iterable will count down with a negative step.

const iterable = range(5, 0);
console.log([...iterable]);
// Output: [5, 4, 3, 2, 1]

You can also specify a step.

const iterable = range(0, 5, 2);
console.log([...iterable]);
// Output: [0, 2, 4]

reduce

Consumes the iterable and reduces it to the reducer function's result.

const iterable = [1, 2, 3, 4, 5];
console.log(reduce(iterable, (accumulator, currentValue) => accumulator + currentValue));
// Output: 15

repeat

Creates an iterable that repeats the input iterable count times.

const iterator = repeat('Hello, world!', 3);
console.log([...iterator]);
// Output: ['Hello, world!', 'Hello, world!', 'Hello, world!']

reverse

Consumes the iterable and returns a new iterable with the elements in reverse order.

console.log([...reverse([1, 2, 3, 4, 5])]);
// Output: [5, 4, 3, 2, 1]

console.log([...reverse('hello')]);
// Output: ['o', 'l', 'l', 'e', 'h']

slice

Produces an iterable with the elements from the start index to the end index (exclusive).

const iterable = [1, 2, 3, 4, 5];
console.log([...slice(iterable, 1, 3)]);
// Output: [2, 3]

const iterable = [1, 2, 3, 4, 5];
console.log([...slice(iterable, -2)]);
// Output: [4, 5]

const iterable = [1, 2, 3, 4, 5];
console.log([...slice(iterable, 2)]);
// Output: [3, 4, 5]

const iterable = [1, 2, 3, 4, 5];
console.log([...slice(iterable, 2, -1)]);
// Output: [3, 4]

const iterable = [1, 2, 3, 4, 5];
console.log([...slice(iterable, -2, -1)]);
// Output: [4]

const iterable = [1, 2, 3, 4, 5];
console.log([...slice(iterable, 2, 1)]);
// Output: []

some

Advances the iterable until it finds a matching element, returning true if it's found and false otherwise.

const iterable = [1, 2, 3, 4, 5];
console.log(some(iterable, value => value % 2 === 0));
// Output: true

const iterable = [1, 2, 3, 4, 5];
console.log(some(iterable, value => value % 6 === 0));
// Output: false

sorted

Consumes the iterable and returns a new iterable with the elements sorted.

const iterable = [5, 3, 1, 4, 2];
console.log([...sorted(iterable)]);
// Output: [1, 2, 3, 4, 5]

starMap

Creates an iterable with the results of calling a provided function on each element of the input iterables as the function's parameters.

const iterable = [
	[1, 2],
	[3, 4],
	[5, 6]
];
console.log([...starMap(iterable, (a, b) => a + b)]);
// Output: [3, 7, 11]

sum

Consumes the iterable and returns the sum of all the elements.

const iterable = [1, 2, 3, 4, 5];
console.log(sum(iterable));
// Output: 15

take

Creates an iterable with the first count elements.

const iterable = [1, 2, 3, 4, 5];
console.log([...take(iterable, 2)]);
// Output: [1, 2]

takeLast

Consumes the iterable and returns a new iterable with the last count elements.

const iterable = [1, 2, 3, 4, 5];
console.log([...takeLast(iterable, 2)]);
// Output: [4, 5]

takeWhile

Alias of filter.

tee

Creates count independent iterators from the input iterable.

const iterable = [1, 2, 3, 4, 5];
const [iter1, iter2] = tee(iterable, 2);

console.log([...iter1]);
// Output: [1, 2, 3, 4, 5]

console.log([...iter2]);
// Output: [1, 2, 3, 4, 5]

toArray

Consumes the iterable and returns an array with all the elements.

const array = [1, 2, 3, 4, 5];
console.log(toArray(array));
// Output: [1, 2, 3, 4, 5]

const set = new Set([1, 2, 3, 4, 5]);
console.log(toArray(set));
// Output: [1, 2, 3, 4, 5]

const map = new Map([
	['a', 1],
	['b', 2],
	['c', 3]
]);
console.log(toArray(map));
// Output: [['a', 1], ['b', 2], ['c', 3]]

const string = 'hello';
console.log(toArray(string));
// Output: ['h', 'e', 'l', 'l', 'o']

toIterableIterator

Creates an iterable iterator from an iterable or iterator-like object.

const array = [1, 2, 3, 4, 5];
console.log([...toIterableIterator(array)]);
// Output: [1, 2, 3, 4, 5]

const set = new Set([1, 2, 3, 4, 5]);
console.log([...toIterableIterator(set)]);
// Output: [1, 2, 3, 4, 5]

const map = new Map([
	['a', 1],
	['b', 2],
	['c', 3]
]);
console.log([...toIterableIterator(map)]);
// Output: [['a', 1], ['b', 2], ['c', 3]]

const string = 'hello';
console.log([...toIterableIterator(string)]);
// Output: ['h', 'e', 'l', 'l', 'o']

union

Creates an iterable with the elements that are in either input iterable.

const iterable1 = [1, 2, 3];
const iterable2 = [3, 4, 5];
console.log([...union(iterable1, iterable2)]);
// Output: [1, 2, 3, 4, 5]

unique

Creates an iterable with the unique elements of the input iterable. Under the hood, it calls union with the iterable itself.

const iterable = [1, 2, 2, 3, 3, 3, 4, 4, 4, 4, 5, 5, 5, 5, 5];
console.log([...unique(iterable)]);
// Output: [1, 2, 3, 4, 5]

unzip

Creates an array for each element of the input iterable, transposing the input iterable. The opposite of zip.

const iterable = [
	[1, 'a'],
	[2, 'b'],
	[3, 'c']
];
const [numbers, letters] = unzip(iterable);

console.log(numbers);
// Output: [1, 2, 3]

console.log(letters);
// Output: ['a', 'b', 'c']

zip

Creates an iterable with the elements of the input iterables zipped together. The opposite of unzip.

const iterable1 = [1, 2, 3];
const iterable2 = ['a', 'b', 'c'];
const iterable3 = [true, false, true];
console.log(zip(iterable1, iterable2, iterable3));
// Output: [
// 	[1, 'a', true],
// 	[2, 'b', false],
// 	[3, 'c', true]
// ]