@sapphire/iterator-utilities
Iterator utilities for JavaScript.
Table of Contents
- Features
- Installation
- Usage
appendataveragechainchunkcompactcompresscontainscountcycledifferencedropdropLastdropWhileemptyenumerateeveryfilterfindfindIndexfirstflatflatMapforEachfromindexOfintersectisEmptylastmapmaxminpartitionpeekableprependproductrangereducerepeatreverseslicesomesortedstarMapsumtaketakeLasttakeWhileteetoArraytoIterableIteratorunionuniqueunzipzip
- Buy us some doughnuts
- Contributors
Features
- Written in TypeScript
- Bundled with esbuild so it can be used in NodeJS and browsers
- Offers CommonJS, ESM and UMD bundles
- Fully tested
Installation
You can use the following command to install this package, or replace npm install with your package manager of choice.
npm install @sapphire/iterator-utilities
Usage
For any of the following examples, you can import the utilities from the index file:
import { append } from '@sapphire/iterator-utilities';
const { append } = require('@sapphire/iterator-utilities');
Or you can import the utilities directly:
import { append } from '@sapphire/iterator-utilities/append';
const { append } = require('@sapphire/iterator-utilities/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]
// ]
Buy us some doughnuts
Sapphire Community is and always will be open source, even if we don't get donations. That being said, we know there are amazing people who may still want to donate just to show their appreciation. Thank you very much in advance!
We accept donations through Open Collective, Ko-fi, PayPal, Patreon and GitHub Sponsorships. You can use the buttons below to donate through your method of choice.
| Donate With | Address |
|---|---|
| Open Collective | Click Here |
| Ko-fi | Click Here |
| Patreon | Click Here |
| PayPal | Click Here |
Contributors
Please make sure to read the Contributing Guide before making a pull request.
Thank you to all the people who already contributed to Sapphire!
Interfaces
| Interface | Description |
|---|---|
| Peekable | - |
Type Aliases
| Type Alias | Description |
|---|---|
| CompareByComparator | - |
| IterableResolvable | - |
| IterableResolved | - |
| LexicographicComparison | Represents the result of a lexicographic comparison. |
| NumberResolvable | - |
| StarMapParameters | - |
| UnzipIterable | - |
| ZipIterators | - |
Variables
| Variable | Description |
|---|---|
| descNumber | - |
| descString | - |
Functions
| Function | Description |
|---|---|
| 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]. |
| ascNumber | Compares two elements using the default comparison algorithm. |
| at | Advances the iterable to the nth element and returns it. If the iterable is exhausted before reaching the nth element, it returns undefined. |
| average | Consumes the iterable and returns the average value of all the elements. If the iterable is empty, it returns null. |
| chain | Similar to append, but takes an iterable of iterables and chains them together. |
| chunk | Chunks the iterable into arrays of at most size elements. |
| collectInto | Collects all the items from an iterator into an array. |
| compact | Creates a new iterable that yields all the non-nullish values (null and undefined) from the iterable. |
| compare | Lexicographically compares the elements of both iterators are equal. |
| compareBy | Lexicographically compares the elements of both iterators are equal. That is: |
| compress | Creates a new iterable of the first iterable based on the truthiness of the corresponding element in the second iterable. |
| contains | Advances the iterable until it finds the element, returning true if it's found and false otherwise. |
| count | Consumes the iterable and returns the number of elements. |
| cycle | Creates an infinite iterable by cycling through the elements of the input iterable. |
| defaultCompare | Compares two elements lexicographically using the default comparison algorithm. |
| difference | Creates an iterable with the elements of the first iterable that are not in the second iterable. |
| drop | Advances the iterable by count elements from the iterable. |
| dropLast | Consumes the iterable, creating a new iterator without the last count elements from the iterable. |
| dropWhile | Creates a new iterator without the elements that satisfy the specified test. |
| empty | Creates an empty iterator. |
| enumerate | Creates a new iterable that yields the index and value of each element. |
| equal | Determines if the elements of both iterators are equal. |
| equalBy | Determines if the elements of both iterators are equal with respect to the specified equality function. |
| every | Tests whether all elements in the iterable pass the test implemented by the provided function. |
| filter | Creates an iterable with the elements that pass the test implemented by the provided function. |
| find | Advances the iterable until it finds the element, returning it if it's found and undefined otherwise. |
| findIndex | Advances the iterable until it finds the element, returning its index if it's found and -1 otherwise. |
| first | Consumes the first element of the iterable, returning it if it's found and undefined otherwise. |
| flat | Creates an iterable that yields the elements of each iterable in the input iterable. |
| flatMap | Creates an iterable that yields the elements of each iterable returned by the provided function on each element of the input iterable. |
| forEach | Executes a provided function once for each iterable element. |
| from | Resolves an iterable from an iterable or iterator-like object. |
| fuse | Creates an iterator which ends after the first done result from the original iterator. |
| greaterOrEqualThan | Determines if the elements of iterable are lexicographically greater or equal than those of another. |
| greaterThan | Determines if the elements of iterable are lexicographically greater than those of another. |
| indexOf | Advances the iterable until it finds the element, returning its index if it's found and -1 otherwise. |
| inspect | Does something with each element of an iterator, passing the value on. |
| intersect | Creates an iterable with the elements that are in both input iterables. |
| intersperse | Creates a new iterator which places separator between adjacent items of the original iterator. |
| isEmpty | Advances the iterable once, returning true if it's exhausted and false otherwise. |
| isSorted | Checks if the elements of this iterator are sorted in ascending order. |
| isSortedBy | Checks if the elements of this iterator are sorted using the given comparator function. |
| isSortedByKey | Checks if the elements of this iterator are sorted using the given key extraction function. |
| last | Consumes the iterable until it's exhausted, returning the last element. |
| lessOrEqualThan | Determines if the elements of iterable are lexicographically less or equal than those of another. |
| lessThan | Determines if the elements of iterable are lexicographically less than those of another. |
| map | Creates an iterable with the results of calling a provided function on each element. |
| max | Consumes the iterable and returns the highest number element. If the iterable is empty, it returns null. |
| maxBy | Returns the element that gives the maximum value with respect to the specified comparison function. |
| maxByKey | Returns the element that gives the maximum value from the specified function. |
| min | Consumes the iterable and returns the lowest number element. If the iterable is empty, it returns null. |
| minBy | Returns the element that gives the minimum value with respect to the specified comparison function. |
| minByKey | Returns the element that gives the minimum value from the specified function. |
| notEqual | Determines if the elements of both iterators are not equal. |
| partition | Consumes the iterable and creates two arrays, one with the elements that pass the test and another with the elements that don't. |
| peekable | Creates an iterator that allows you to peek at the next element without advancing the iterator. |
| prepend | Creates an iterator with the provided iterables prepended to the first iterable. |
| product | Consumes the iterable and returns the product of all the elements. If the iterable is empty, it returns 1. |
| range | Creates an iterable with the numbers from start to stop (exclusive) with an optional step. |
| reduce | Consumes the iterable and reduces it to the reducer function's result. |
| repeat | Creates an iterable that repeats the input iterable count times. |
| reverse | Consumes the iterable and returns a new iterable with the elements in reverse order. |
| slice | Produces an iterable with the elements from the start index to the end index (exclusive). |
| some | Advances the iterable until it finds a matching element, returning true if it's found and false otherwise. |
| sorted | Consumes the iterable and returns a new iterable with the elements sorted. |
| starMap | Creates an iterable with the results of calling a provided function on each element of the input iterables as the function's parameters. |
| stepBy | Creates an iterator starting at the same point, but stepping by the given amount at each iteration. |
| sum | Consumes the iterable and returns the sum of all the elements. |
| take | Creates an iterable with the first count elements. |
| takeLast | Consumes the iterable and returns a new iterable with the last count elements. |
| tee | Creates count independent iterators from the input iterable. |
| toArray | Consumes the iterable and returns an array with all the elements. |
| toIterableIterator | Creates an iterable iterator from an iterable or iterator-like object. |
| union | Creates an iterable with the elements that are in either input iterable. |
| unique | Creates an iterable with the unique elements of the input iterable. Under the hood, it calls union with the iterable itself. |
| unzip | Creates an array for each element of the input iterable, transposing the input iterable. The opposite of zip. |
| windows | Creates an iterable with arrays of count elements representing a sliding window. |
| zip | Creates an iterable with the elements of the input iterables zipped together. The opposite of unzip. |
References
all
Renames and re-exports every
any
Renames and re-exports some
ascString
Renames and re-exports defaultCompare
collect
Renames and re-exports toArray
concat
Renames and re-exports append
eq
Renames and re-exports equal
eqBy
Renames and re-exports equalBy
except
Renames and re-exports difference
ge
Renames and re-exports greaterOrEqualThan
gt
Renames and re-exports greaterThan
le
Renames and re-exports lessOrEqualThan
lt
Renames and re-exports lessThan
ne
Renames and re-exports notEqual
nth
Renames and re-exports at
omit
Renames and re-exports difference
position
Renames and re-exports indexOf
skip
Renames and re-exports drop
skipLast
Renames and re-exports dropLast
skipWhile
Renames and re-exports dropWhile
takeWhile
Renames and re-exports filter