Type-safe utilities for iterating through Lists, Arrays, and Sets.
You can use the following command to install this package, or replace pnpm add with your package manager of choice.
pnpm add -D @flowr/iteratorFor 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');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]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: 3Consumes 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: 3Similar 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]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]]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]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]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: trueConsumes the iterable and returns the number of elements.
const iterable = [1, 2, 3, 4, 5];
console.log(count(iterable));
// Output: 5Creates 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, ...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]Advances the iterable by count elements from the iterable.
const iterable = drop(iterator, 2);
console.log([...iterable]);
// Output: [3, 4, 5]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]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]Creates an empty iterator.
const iterable = empty();
console.log([...iterable]);
// Output: []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: cTests 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: falseCreates 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]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: 2Advances 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: 1Consumes 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: 1Creates 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]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]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, 5Resolves 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, 5Advances 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: 2Creates 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]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: falseConsumes the iterable until it's exhausted, returning the last element.
const iterable = [1, 2, 3, 4, 5];
console.log(last(iterable));
// Output: 5Creates 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]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: 5Consumes 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: 1Consumes 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]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 }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]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: 120Creates 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]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: 15Creates 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!']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']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: []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: trueconst iterable = [1, 2, 3, 4, 5];
console.log(some(iterable, value => value % 6 === 0));
// Output: falseConsumes 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]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]Consumes the iterable and returns the sum of all the elements.
const iterable = [1, 2, 3, 4, 5];
console.log(sum(iterable));
// Output: 15Creates an iterable with the first count elements.
const iterable = [1, 2, 3, 4, 5];
console.log([...take(iterable, 2)]);
// Output: [1, 2]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]Alias of filter.
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]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']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']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]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]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']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]
// ]