Utilities for JavaScript Iterable and AsyncIterable
npm install iterable-operatorIterable and AsyncIterable.sh
npm install --save iterable-operator
or
yarn add iterable-operator
`Usage
ts
import { map, toArray } from 'iterable-operator'const iter = [1, 2, 3]
const doubleIter = map(iter, x => x * 2)
const result = toArray(doubleIter)
`You may need [a pipe function].
[a pipe function]: https://github.com/BlackGlory/extra-utils
API
$3
ts
function isIterable(val: unknown): val is Iterable
function isntIterable(val: T): val is Exclude>
`$3
ts
function isAsyncIterable(val: unknown): val is AsyncIterable
function isntAsyncIterable(
val: T
): val is Exclude>
`$3
ts
function chunk(
iterable: Iterable
, size: number // size > 0
): IterableIterator
function chunkAsync(
iterable: AsyncIterable
, size: number // size > 0
): AsyncIterableIterator>>
`ts
chunk([1, 2, 3], 2) // [[1, 2], [3]]
chunk([1, 2, 3], 3) // [[1, 2, 3]]
chunk([1, 2, 3], 5) // [[1, 2, 3]]
chunk([1, 2, 3], 0) // throw Error
chunk([1, 2, 3], -1) // throw Error
`The memory usage of this function depends on
.$3
`ts
function chunkBy(
iterable: Iterable
, predicate: (element: T, index: number) => unknown
): IterableIterator
function chunkByAsync(
iterable: Iterable | AsyncIterable
, predicate: (element: Awaited, index: number) => Awaitable
): AsyncIterableIterator>>
`ts
chunkBy([1, 2, 3], x => x === 2) // [[1, 2], [3]]
chunkBy([1, 2, 3], x => x === 3) // [[1, 2, 3]]
chunkBy([1, 2, 3], x => x === 5) // [[1, 2, 3]]
`The memory usage of this function depends on
and predicate.$3
`ts
function concat(
iterable: Iterable
, ...otherIterables: Iterable[]
): IterableIterator
function concatAsync(
iterable: Iterable | AsyncIterable
, ...otherIterables: Array> | AsyncIterable>>
): AsyncIterableIterator | Awaited>
`ts
concat([1, 2, 3]) // [1, 2, 3]
concat([1, 2, 3], ['a', 'b', 'c']) // [1, 2, 3, 'a', 'b', 'c']
`$3
ts
function difference(left: Iterable, right: Iterable): IterableIterator
function differenceAsync(
left: Iterable> | AsyncIterable>
, right: Iterable> | AsyncIterable>
): AsyncIterableIterator>
`ts
difference([1, 2, 3], [3, 4, 5]) // [1, 2]
`The memory usage of this function depends on
.$3
`ts
function drop(
iterable: Iterable
, count: number // count >= 0
): IterableIterator
function dropAsync(
iterable: AsyncIterable
, count: number // count >= 0
): AsyncIterableIterator>
`ts
drop([1, 2, 3], 0) // [1, 2, 3]
drop([1, 2, 3], 2) // [3]
drop([1, 2, 3], 3) // []
drop([1, 2, 3], 5) // []
drop([1, 2, 3], -1) // throw Error
`$3
ts
function dropRight(
iterable: Iterable
, count: number // count >= 0
): IterableIterator
function dropRightAsync(
iterable: AsyncIterable
, count: number // count >= 0
): AsyncIterableIterator>
`ts
dropRight([1, 2, 3], 0) // [1, 2, 3]
dropRight([1, 2, 3], 2) // [1]
dropRight([1, 2, 3], 3) // []
dropRight([1, 2, 3], 5) // []
dropRight([1, 2, 3], -1) // throw Error
`The memory usage of this function depends on
.$3
`ts
function dropUntil(
iterable: Iterable
, predicate: (element: T, index: number) => unknown
): IterableIterator
function dropUntilAsync(
iterable: Iterable | AsyncIterable
, predicate: (element: Awaited, index: number) => Awaitable
): AsyncIterableIterator>
`ts
dropUntil([1, 2, 3], x => x === 2) // [2, 3]
`The memory usage of this function depends on
and predicate.$3
`ts
function filter(
iterable: Iterable
, predicate: (element: T, index: number) => unknown
): IterableIterator
function filterAsync = Awaited>(
iterable: Iterable | AsyncIterable
, predicate: (element: Awaited, index: number) => Awaitable
): AsyncIterableIterator
`ts
filter([1, 2, 3], x => x % 2 === 1) // [1, 3]
`$3
ts
function flatten(iterable: Iterable): IterableIterator
function flattenAsync(iterable: AsyncIterable): AsyncIterableIterator
`ts
flatten([]) // []
flatten('123') // ['1', '2', '3']
flatten(['one', ['two'], 0, [1, [2]]]) // ['o', 'n', 'e', 'two', 0, 1, [2]]
`$3
ts
function flattenDeep(
iterable: Iterable
, depth: number = Infinity // depth >= 0
): IterableIterator
function flattenDeepAsync(
iterable: AsyncIterable
, depth: number = Infinity // depth >= 0
): AsyncIterableIterator
`ts
flattenDeep([]) // []
flattenDeep('123') // ['1', '2', '3']
flattenDeep([], -1) // throw Error
flattenDeep([0, [1]], 0) // [0, [1]]
flattenDeep(['one', ['two', ['three']], 0, [1, [2, [3]]]], 2) // ['o', 'n', 'e', 't', 'w', 'o', 'three', 0, 1, 2, [3]]
`$3
ts
function flattenBy(
iterable: Iterable
, predicate: (element: unknown, level: number) => boolean
): IterableIterator
function flattenByAsync(
iterable: Iterable | AsyncIterable
, predicate: (element: unknown, level: number) => Awaitable
): AsyncIterableIterator
`ts
flattenBy(['one', ['two'], 0, [1]], x => typeof x !== 'string') // ['one', 'two', 0, 1]
flattenBy([], () => true) // []
flattenBy('123', () => true) // ['1', '2', '3']
`$3
ts
function intersection(left: Iterable, right: Iterable): IterableIterator
function intersectionAsync(
left: Iterable> | AsyncIterable
, right: Iterable> | AsyncIterable
): AsyncIterableIterator>
`The memory usage of this function depends on
.`ts
intersection([1, 2], [2, 3]) // [2]
`$3
ts
function map(
iterable: Iterable
, fn: (element: T, index: number) => U
): IterableIterator
function mapAsync(
iterable: Iterable | AsyncIterable
, fn: (element: Awaited, index: number) => Awaitable
): AsyncIterableIterator>
`ts
map([1, 2, 3], x => x * 2) // [2, 4, 6]
`$3
ts
function flatMap(
iterable: Iterable
, fn: (element: T, index: number) => Iterable
): IterableIterator
function flatMapAsync(
iterable: Iterable | AsyncIterable
, fn: (element: Awaited, index: number) => Awaitable | AsyncIterable>
): AsyncIterableIterator>
`ts
map([1, 2, 3], x => [x, x * 2]) // [1, 2, 2, 4, 3, 6]
`$3
ts
function repeat(
iterable: Iterable
, times: number // times >= 0
): IterableIterator
function repeatAsync(
iterable: AsyncIterable
, times: number // times >= 0
): AsyncIterableIterator>
`ts
repeat([1, 2, 3], 2) // [1, 2, 3, 1, 2, 3]
repeat([1, 2, 3], 0) // []
repeat([1, 2, 3], -1) // throw Error
`The memory usage of this function depends on
.$3
`ts
function slice(
iterable: Iterable
, start: number // start >= 0
, end: number = Infinity // end >= start
): IterableIterator
function sliceAsync(
iterable: AsyncIterable
, start: number // start >= 0
, end: number = Infinity // end >= start
): AsyncIterableIterator>
`ts
slice([1, 2, 3], -1, 1) // throw Error
slice([1, 2, 3], 3, 5) // []
slice([1, 2, 3], 1, 2) // [2]
slice([1, 2, 3], 1, 1) // []
slice([1, 2, 3], 2, 1) // throw Error
`$3
ts
function join(iterable: Iterable, separator: U): IterableIterator
function joinAsync(
iterable: AsyncIterable
, separator: U
): AsyncIterableIterator | U>
`ts
join([1, 2, 3], '+') // [1, '+', 2, '+', 3]
`$3
ts
function split(iterable: Iterable, separator: T): IterableIterator
function splitAsync(
iterable: AsyncIterable
, separator: T
): AsyncIterableIterator>>
`ts
split([1, 2, 3, 4, 5], 3) // [[1, 2], [4, 5]]
split([1, 2, 3, 4, 5], 1) // [[], [2, 3, 4, 5]]
split([1, 2, 3, 4, 5], 5) // [[1, 2, 3, 4], []]
split([1, 2, 3, 4, 5], 0) // [[1, 2, 3, 4, 5]]
`The memory usage of this function depends on
and separator.$3
`ts
function splitBy(
iterable: Iterable
, predicate: (element: T, index: number) => unknown
): IterableIterator
function splitByAsync(
iterable: Iterable | AsyncIterable
, predicate: (element: Awaited, index: number) => Awaitable
): AsyncIterableIterator>>
`ts
splitBy([1, 2, 3, 4, 5], x => x === 3) // [[1, 2], [4, 5]]
splitBy([1, 2, 3, 4, 5], x => x === 1) // [[], [2, 3, 4, 5]]
splitBy([1, 2, 3, 4, 5], x => x === 5) // [[1, 2, 3, 4], []]
splitBy([1, 2, 3, 4, 5], x => x === 0) // [[1, 2, 3, 4, 5]]
`The memory usage of this function depends on
and predicate.$3
`ts
function take(iterable: Iterable, count: number): IterableIterator
function takeAsync(
iterable: AsyncIterable
, count: number
): AsyncIterableIterator>
`ts
take([1, 2, 3], 5) // [1, 2, 3]
take([1, 2, 3], 2) // [1, 2]
take([1, 2, 3], 0) // []
take([1, 2, 3], -1) // throw Error
`$3
ts
function takeRight(iterable: Iterable, count: number): IterableIterator
function takeRightAsync(
iterable: AsyncIterable
, count: number
): AsyncIterableIterator>
`ts
takeRight([1, 2, 3], 2) // [2, 3]
takeRight([1, 2, 3], 5) // [1, 2, 3]
takeRight([1, 2, 3], 0) // []
takeRight([1, 2, 3], -1) // throw Error
`The memory usage of this function depends on
.$3
`ts
function takeUntil(
iterable: Iterable
, predicate: (element: T, index: number) => unknown
): IterableIterator
function takeUntilAsync(
iterable: Iterable | AsyncIterable
, predicate: (element: Awaited, index: number) => Awaitable
): AsyncIterableIterator>
`ts
takeUntil([1, 2, 3], x => x === 2) // [1]
`$3
ts
function tap(
iterable: Iterable
, fn: (element: T, index: number) => unknown
): IterableIterator
function tapAsync(
iterable: Iterable | AsyncIterable
, fn: (element: Awaited, index: number) => Awaitable
): AsyncIterableIterator>
`ts
tap([1, 2, 3], x => console.log(x)) // [1, 2, 3]
`$3
ts
function toAsyncIterable(
iterable: Iterable>
): AsyncIterableIterator>
`ts
toAsyncIterable([1, 2, 3]) // AsyncIterable [1, 2, 3]
`$3
ts
function transform(
iterable: Iterable
, transformer: (iterable: Iterable) => Iterable
): IterableIterator
function transformAsync(
iterable: Iterable
, transformer: (iterable: Iterable) => AsyncIterable
): AsyncIterableIterator>
function transformAsync(
iterable: AsyncIterable
, transformer: (iterable: AsyncIterable) => AsyncIterable
): AsyncIterableIterator>
`ts
transform([1, 2, 3], function* double(iter) {
for (const element of iter) {
yield element * 2
}
}) // [2, 4, 6]
`$3
ts
function uniq(iterable: Iterable): IterableIterator
function uniqAsync(iterable: AsyncIterable): AsyncIterableIterator>
`ts
uniq([1, 1, 2, 2, 3, 3]) // [1, 2, 3]
`The memory usage of this function depends on
.$3
`ts
function uniqBy(
iterable: Iterable
, fn: (element: T, index: number) => U
): IterableIterator
function uniqByAsync(
iterable: Iterable | AsyncIterable
, fn: (element: Awaited, index: number) => Awaitable
): AsyncIterableIterator>
`ts
uniqBy([1, 2, 3], x => x % 2) // [1, 2]
`The memory usage of this function depends on
.$3
`ts
function zip>>(
iterable: Iterable
, ...otherIterables: U
): IterableIterator<[T, ...ExtractTypeTupleFromIterableTuple]>
function zipAsync<
T
, U extends Array> | AsyncIterable>>
>(
iterable: Iterable> | AsyncIterable>
, ...otherIterables: U
): AsyncIterableIterator<
[Awaited, ...ExtractTypeTupleFromAsyncLikeIterableTuple]
>
`ts
zip([1, 2, 3], ['a', 'b', 'c']) // [[1, 'a'], [2, 'b'], [3, 'c']]
zip([1, 2, 3], ['a', 'b']) // [[1, 'a'], [2, 'b']
zip([1, 2, 3], ['a', 'b'], ['i', 'ii', 'iii']) // [[1, 'a', 'i'], [2, 'b', 'ii']]
`$3
ts
function consume(iterable: Iterable, consumer: (iterable: Iterable) => U): U
function consumeAsync(
iterable: Iterable
, consumer: (iterable: Iterable) => Awaitable
): Promise>
function consumeAsync(
iterable: AsyncIterable
, consumer: (iterable: AsyncIterable) => Awaitable
): Promise>
`ts
consume([1, 2, 3], xs => new Set(xs)) // Set [1, 2, 3]
`$3
ts
function each(
iterable: Iterable
, fn: (element: T, index: number) => unknown
): void
function eachAsync(
iterable: Iterable | AsyncIterable
, fn: (element: Awaited, index: number) => Awaitable
): Promise
`ts
each([1, 2, 3], x => console.log(x)) // void
`$3
ts
function every(
iterable: Iterable
, predicate: (element: T, index: number) => unknown
): boolean
function everyAsync(
iterable: Iterable | AsyncIterable
, predicate: (element: Awaited, index: number) => Awaitable
): Promise
`ts
every([1, 2, 3], x => x < 5) // true
every([1, 2, 3], x => x <= 2) // false
`$3
ts
function find(
iterable: Iterable
, predicate: (element: T, index: number) => unknown
): T | undefined
function findAsync(
iterable: Iterable | AsyncIterable
, predicate: (element: Awaited, index: number) => Awaitable
): Promise | undefined>
`ts
find([1, 2, 3], x => x === 2) // 2
find([1, 2, 3], x => x === 4) // undefined
`$3
ts
function findAllIndexes(
iterable: Iterable
, predicate: (value: T, index: number) => unknown
): IterableIterator
`ts
findAllIndexes([1, 2, 3], x => x % 2 === 1) // [0, 2]
`$3
ts
function first(iterable: Iterable): T | undefined
function firstAsync(iterable: AsyncIterable): Promise | undefined>
`ts
first([1, 2, 3]) // 1
first([]) // undefined
`$3
ts
function includes(iterable: Iterable, value: T): boolean
function includesAsync(
iterable: AsyncIterable
, value: Awaited
): Promise
`ts
includes([1, 2, 3], 2) // true
includes([1, 2, 3], 4) // false
`$3
ts
function last(iterable: Iterable): T | undefined
function lastAsync(iterable: AsyncIterable): Promise | undefined>
`ts
last([1, 2, 3]) // 3
last([]) // undefined
`$3
ts
function reduce(
iterable: Iterable
, fn: (accumulator: T, currentValue: T, index: number) => T
): T
function reduce(
iterable: Iterable
, fn: (accumulator: U, currentValue: T, index: number) => U
, initialValue: U
): U
function reduceAsync(
iterable: Iterable | AsyncIterable
, fn: (
accumulator: Awaited
, currentValue: Awaited
, index: number
) => Awaitable>
): Promise>
function reduceAsync(
iterable: Iterable | AsyncIterable
, fn: (accumulator: Awaited, currentValue: Awaited, index: number) => Awaitable
, initialValue: U
): Promise>
`ts
reduce([], (acc, cur) => acc + cur) // throw Error
reduce([1], (acc, cur) => acc + cur) // 1
reduce([1, 2, 3], (acc, cur) => acc + cur) // 6reduce([1, 2, 3], (acc, cur, index) => {
acc.push([cur, index])
return acc
}) // [[1, 0], [2, 1], [3, 2]]
`$3
ts
function some(
iterable: Iterable
, predicate: (element: T, index: number) => unknown
): boolean
function someAsync(
iterable: Iterable | AsyncIterable
, predicate: (element: Awaited, index: number) => Awaitable
): Promise
`ts
some([1, 2, 3], x => x === 2) // true
some([1, 2, 3], x => x === 4) // false
`$3
ts
function toArray(iterable: Iterable): T[]
function toArrayAsync(
iterable: AsyncIterable
): Promise>>
`ts
toArray([1, 2, 3]) // Array [1, 2, 3]
`$3
ts
function toSet(iterable: Iterable): Set
function toSetAsync(
iterable: Iterable | AsyncIterable
): Promise>>
`ts
toSet([1, 1, 2, 2, 3, 3]) // Set [1, 2, 3]
`$3
ts
function count(iterable: Iterable): number
function countAsync(iterable: AsyncIterable): Promise
`ts
count([1, 2, 3]) // 3
`$3
ts
function groupBy(
iterable: Iterable
, fn: (element: T, index: number) => U
): Map
function groupByAsync(
iterable: Iterable | AsyncIterable
, fn: (element: Awaited, index: number) => Awaitable
): Promise, Array>>>
`ts
groupBy([1, 2, 3], x => x % 2) // { 1: [1, 3], 0: [2] }
`$3
ts
function prefetch(iterable: Iterable, size: number): AsyncIterableIterator
function prefetchAsync(
iterable: AsyncIterable
, size: number
): AsyncIterableIterator
`$3
ts
function top(
iterable: Iterable
, num: number
, compare: (a: T, b: T) => number
): T[]
function topAsync(
iterable: AsyncIterable
, num: number
, compare: (a: Awaited, b: Awaited) => number
): Promise>>
`ts
top([1, 2, 3], 2, (a, b) => b - a) // [3, 2]
`$3
ts
function avg(iterable: Iterable): number
function avgAsync(iterable: AsyncIterable): Promise
`ts
avg([1, 2, 3]) // 2
``