Opinionated collection of common iterator utilities
npm install @flowr/iteratorType-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.
``sh`
pnpm add -D @flowr/iterator
For any of the following examples, you can import the utilities from the index file:
`ts`
import { append } from '@flowr/iterator';
Or you can import the utilities directly:
`ts`
import { append } from '@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].
`typescript`
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.
`typescript`
const iterable = [1, 2, 3, 4, 5];
console.log(at(iterable, 2));
// Output: 3
Consumes the iterable and returns the average value of all the elements. If the iterable is empty, it returns null.
`typescript`
const iterable = [1, 2, 3, 4, 5];
console.log(average(iterable));
// Output: 3
Similar to append, but takes an iterable of iterables and chains them together.
`typescript`
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.
`typescript`
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.
`typescript`
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.
`typescript`
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.
`typescript`
const iterable = [1, 2, 3, 4, 5];
console.log(contains(iterable, 3));
// Output: true
Consumes the iterable and returns the number of elements.
`typescript`
const iterable = [1, 2, 3, 4, 5];
console.log(count(iterable));
// Output: 5
Creates an infinite iterable by cycling through the elements of the input iterable.
`typescript`
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.
`typescript`
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.
`typescript`
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.
`typescript`
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.
`typescript`
const iterable = dropWhile([1, 2, 3, 4, 5], value => value < 3);
console.log([...iterable]);
// Output: [3, 4, 5]
Creates an empty iterator.
`typescript`
const iterable = empty();
console.log([...iterable]);
// Output: []
Creates a new iterable that yields the index and value of each element.
`typescriptIndex: ${index}, Value: ${value}
const iterable = ['a', 'b', 'c'];
for (const [index, value] of enumerate(iterable))
console.log();`
// Output: Index: 0, Value: a
// Output: Index: 1, Value: b
// Output: Index: 2, Value: c
Tests whether all elements in the iterable pass the test implemented by the provided function.
`typescript`
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
Creates an iterable with the elements that pass the test implemented by the provided function.
`typescript`
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.
`typescript`
const iterable = [1, 2, 3, 4, 5];
console.log(find(iterable, value => value % 2 === 0));
// Output: 2
Advances the iterable until it finds the element, returning its index if it's found and -1 otherwise.
`typescript`
const iterable = [1, 2, 3, 4, 5];
console.log(findIndex(iterable, value => value % 2 === 0));
// Output: 1
Consumes the first element of the iterable, returning it if it's found and undefined otherwise.
`typescript`
const iterable = [1, 2, 3, 4, 5];
console.log(first(iterable));
// Output: 1
Creates an iterable that yields the elements of each iterable in the input iterable.
`typescript`
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.
`typescript`
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.
`typescript`
const iterable = [1, 2, 3, 4, 5];
forEach(iterable, value => console.log(value));
// Output: 1, 2, 3, 4, 5
Resolves an iterable from an iterable or iterator-like object.
`typescript`
const iterable = from([1, 2, 3, 4, 5]);
for (const element of iterable)
console.log(element);
// Output: 1, 2, 3, 4, 5
Advances the iterable until it finds the element, returning its index if it's found and -1 otherwise.
`typescript`
const iterable = [1, 2, 3, 4, 5];
console.log(indexOf(iterable, 3));
// Output: 2
Creates an iterable with the elements that are in both input iterables.
`typescript`
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.
`typescript
console.log(isEmpty([]));
// Output: true
console.log(isEmpty([1, 2, 3, 4, 5]));
// Output: false
`
Consumes the iterable until it's exhausted, returning the last element.
`typescript`
const iterable = [1, 2, 3, 4, 5];
console.log(last(iterable));
// Output: 5
Creates an iterable with the results of calling a provided function on each element.
`typescript`
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.
`typescript`
const iterable = [1, 2, 3, 4, 5];
console.log(max(iterable));
// Output: 5
Consumes the iterable and returns the lowest number element. If the iterable is empty, or contains only non-number values, it returns null.
`typescript`
const iterable = [1, 2, 3, 4, 5];
console.log(min(iterable));
// Output: 1
Consumes the iterable and creates two arrays, one with the elements that pass the test and another with the elements that don't.
`typescript
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.
`typescript
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.
`typescript`
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.
`typescript`
const iterable = [1, 2, 3, 4, 5];
console.log(product(iterable));
// Output: 120
Creates an iterable with the numbers from start to stop (exclusive) with an optional step.
`typescript`
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.
`typescript`
const iterable = range(5, 0);
console.log([...iterable]);
// Output: [5, 4, 3, 2, 1]
You can also specify a step.
`typescript`
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.
`typescript`
const iterable = [1, 2, 3, 4, 5];
console.log(reduce(iterable, (accumulator, currentValue) => accumulator + currentValue));
// Output: 15
Creates an iterable that repeats the input iterable count times.
`typescript`
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.
`typescript
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).
`typescript`
const iterable = [1, 2, 3, 4, 5];
console.log([...slice(iterable, 1, 3)]);
// Output: [2, 3]
`typescript`
const iterable = [1, 2, 3, 4, 5];
console.log([...slice(iterable, -2)]);
// Output: [4, 5]
`typescript`
const iterable = [1, 2, 3, 4, 5];
console.log([...slice(iterable, 2)]);
// Output: [3, 4, 5]
`typescript`
const iterable = [1, 2, 3, 4, 5];
console.log([...slice(iterable, 2, -1)]);
// Output: [3, 4]
`typescript`
const iterable = [1, 2, 3, 4, 5];
console.log([...slice(iterable, -2, -1)]);
// Output: [4]
`typescript`
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.
`typescript`
const iterable = [1, 2, 3, 4, 5];
console.log(some(iterable, value => value % 2 === 0));
// Output: true
`typescript`
const iterable = [1, 2, 3, 4, 5];
console.log(some(iterable, value => value % 6 === 0));
// Output: false
Consumes the iterable and returns a new iterable with the elements sorted.
`typescript`
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.
`typescript`
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.
`typescript`
const iterable = [1, 2, 3, 4, 5];
console.log(sum(iterable));
// Output: 15
Creates an iterable with the first count elements.
`typescript`
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.
`typescript`
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.
`typescript
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.
`typescript`
const array = [1, 2, 3, 4, 5];
console.log(toArray(array));
// Output: [1, 2, 3, 4, 5]
`typescript`
const set = new Set([1, 2, 3, 4, 5]);
console.log(toArray(set));
// Output: [1, 2, 3, 4, 5]
`typescript`
const map = new Map([
['a', 1],
['b', 2],
['c', 3]
]);
console.log(toArray(map));
// Output: [['a', 1], ['b', 2], ['c', 3]]
`typescript`
const string = 'hello';
console.log(toArray(string));
// Output: ['h', 'e', 'l', 'l', 'o']
Creates an iterable iterator from an iterable or iterator-like object.
`typescript`
const array = [1, 2, 3, 4, 5];
console.log([...toIterableIterator(array)]);
// Output: [1, 2, 3, 4, 5]
`typescript`
const set = new Set([1, 2, 3, 4, 5]);
console.log([...toIterableIterator(set)]);
// Output: [1, 2, 3, 4, 5]
`typescript`
const map = new Map([
['a', 1],
['b', 2],
['c', 3]
]);
console.log([...toIterableIterator(map)]);
// Output: [['a', 1], ['b', 2], ['c', 3]]
`typescript`
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.
`typescript`
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.
`typescript`
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.
`typescript
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.
`typescript``
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]
// ]