iterable-operator

Utilities for JavaScript Iterable and AsyncIterable.

Install

1npm install --save iterable-operator
2# or
3yarn add iterable-operator

Usage

1import { map, toArray } from 'iterable-operator'
2
3const iter = [1, 2, 3]
4const doubleIter = map(iter, x => x * 2)
5const result = toArray(doubleIter)

You may need a pipe function.

API

isIterable

1function isIterable<T>(val: unknown): val is Iterable<T>
2function isntIterable<T>(val: T): val is Exclude<T, Iterable<unknown>>

isAsyncIterable

1function isAsyncIterable<T>(val: unknown): val is AsyncIterable<T>
2function isntAsyncIterable<T>(
3  val: T
4): val is Exclude<T, AsyncIterable<unknown>>

chunk, chunkAsync

1function chunk<T>(
2  iterable: Iterable<T>
3, size: number // size > 0
4): IterableIterator<T[]>
5function chunkAsync<T>(
6  iterable: AsyncIterable<T>
7, size: number // size > 0
8): AsyncIterableIterator<Array<Awaited<T>>>

1chunk([1, 2, 3], 2) // [[1, 2], [3]]
2chunk([1, 2, 3], 3) // [[1, 2, 3]]
3chunk([1, 2, 3], 5) // [[1, 2, 3]]
4chunk([1, 2, 3], 0) // throw Error
5chunk([1, 2, 3], -1) // throw Error

The memory usage of this function depends on size.

chunkBy, chunkByAsync

1function chunkBy<T>(
2  iterable: Iterable<T>
3, predicate: (element: T, index: number) => unknown
4): IterableIterator<T[]>
5function chunkByAsync<T>(
6  iterable: Iterable<T> | AsyncIterable<T>
7, predicate: (element: Awaited<T>, index: number) => Awaitable<unknown>
8): AsyncIterableIterator<Array<Awaited<T>>>

1chunkBy([1, 2, 3], x => x === 2) // [[1, 2], [3]]
2chunkBy([1, 2, 3], x => x === 3) // [[1, 2, 3]]
3chunkBy([1, 2, 3], x => x === 5) // [[1, 2, 3]]

The memory usage of this function depends on iterable and predicate.

concat, concatAsync

1function concat<T, U>(
2  iterable: Iterable<T>
3, ...otherIterables: Iterable<U>[]
4): IterableIterator<T | U>
5function concatAsync<T, U>(
6  iterable: Iterable<T> | AsyncIterable<T>
7, ...otherIterables: Array<Iterable<Awaitable<U>> | AsyncIterable<Awaitable<U>>>
8): AsyncIterableIterator<Awaited<T> | Awaited<U>>

1concat([1, 2, 3]) // [1, 2, 3]
2concat([1, 2, 3], ['a', 'b', 'c']) // [1, 2, 3, 'a', 'b', 'c']

difference, differenceAsync

1function difference<T>(left: Iterable<T>, right: Iterable<T>): IterableIterator<T>
2function differenceAsync<T>(
3  left: Iterable<Awaitable<T>> | AsyncIterable<Awaitable<T>>
4, right: Iterable<Awaitable<T>> | AsyncIterable<Awaitable<T>>
5): AsyncIterableIterator<Awaited<T>>

1difference([1, 2, 3], [3, 4, 5]) // [1, 2]

The memory usage of this function depends on right.

drop, dropAsync

1function drop<T>(
2  iterable: Iterable<T>
3, count: number // count >= 0
4): IterableIterator<T>
5function dropAsync<T>(
6  iterable: AsyncIterable<T>
7, count: number // count >= 0
8): AsyncIterableIterator<Awaited<T>>

1drop([1, 2, 3], 0) // [1, 2, 3]
2drop([1, 2, 3], 2) // [3]
3drop([1, 2, 3], 3) // []
4drop([1, 2, 3], 5) // []
5drop([1, 2, 3], -1) // throw Error

dropRight, dropRightAsync

1function dropRight<T>(
2  iterable: Iterable<T>
3, count: number // count >= 0
4): IterableIterator<T>
5function dropRightAsync<T>(
6  iterable: AsyncIterable<T>
7, count: number // count >= 0
8): AsyncIterableIterator<Awaited<T>>

1dropRight([1, 2, 3], 0) // [1, 2, 3]
2dropRight([1, 2, 3], 2) // [1]
3dropRight([1, 2, 3], 3) // []
4dropRight([1, 2, 3], 5) // []
5dropRight([1, 2, 3], -1) // throw Error

The memory usage of this function depends on iterable.

dropUntil, dropUntilAsync

1function dropUntil<T>(
2  iterable: Iterable<T>
3, predicate: (element: T, index: number) => unknown
4): IterableIterator<T>
5function dropUntilAsync<T>(
6  iterable: Iterable<T> | AsyncIterable<T>
7, predicate: (element: Awaited<T>, index: number) => Awaitable<unknown>
8): AsyncIterableIterator<Awaited<T>>

1dropUntil([1, 2, 3], x => x === 2) // [2, 3]

The memory usage of this function depends on iterable and predicate.

filter, filterAsync

1function filter<T, U extends T = T>(
2  iterable: Iterable<T>
3, predicate: (element: T, index: number) => unknown
4): IterableIterator<U>
5function filterAsync<T, U extends Awaited<T> = Awaited<T>>(
6  iterable: Iterable<T> | AsyncIterable<T>
7, predicate: (element: Awaited<T>, index: number) => Awaitable<unknown>
8): AsyncIterableIterator<U>

1filter([1, 2, 3], x => x % 2 === 1) // [1, 3]

flatten, flattenAsync

1function flatten<T>(iterable: Iterable<unknown>): IterableIterator<T>
2function flattenAsync<T>(iterable: AsyncIterable<unknown>): AsyncIterableIterator<T>

1flatten([]) // []
2flatten('123') // ['1', '2', '3']
3flatten(['one', ['two'], 0, [1, [2]]]) // ['o', 'n', 'e', 'two', 0, 1, [2]]

flattenDeep, flattenDeepAsync

1function flattenDeep<T>(
2  iterable: Iterable<unknown>
3, depth: number = Infinity // depth >= 0
4): IterableIterator<T>
5function flattenDeepAsync<T>(
6  iterable: AsyncIterable<unknown>
7, depth: number = Infinity // depth >= 0
8): AsyncIterableIterator<T>

1flattenDeep([]) // []
2flattenDeep('123') // ['1', '2', '3']
3flattenDeep([], -1) // throw Error
4flattenDeep([0, [1]], 0) // [0, [1]]
5flattenDeep(['one', ['two', ['three']], 0, [1, [2, [3]]]], 2) // ['o', 'n', 'e', 't', 'w', 'o', 'three', 0, 1, 2, [3]]

flattenBy, flattenByAsync

1function flattenBy<T>(
2  iterable: Iterable<unknown>
3, predicate: (element: unknown, level: number) => boolean
4): IterableIterator<T>
5function flattenByAsync<T>(
6  iterable: Iterable<unknown> | AsyncIterable<unknown>
7, predicate: (element: unknown, level: number) => Awaitable<unknown>
8): AsyncIterableIterator<T>

1flattenBy(['one', ['two'], 0, [1]], x => typeof x !== 'string') // ['one', 'two', 0, 1]
2flattenBy([], () => true) // []
3flattenBy('123', () => true) // ['1', '2', '3']

intersection, intersectionAsync

1function intersection<T>(left: Iterable<T>, right: Iterable<T>): IterableIterator<T>
2function intersectionAsync<T>(
3  left: Iterable<Awaitable<T>> | AsyncIterable<T>
4, right: Iterable<Awaitable<T>> | AsyncIterable<T>
5): AsyncIterableIterator<Awaited<T>>

The memory usage of this function depends on right.

1intersection([1, 2], [2, 3]) // [2]

map, mapAsync

1function map<T, U>(
2  iterable: Iterable<T>
3, fn: (element: T, index: number) => U
4): IterableIterator<U>
5function mapAsync<T, U>(
6  iterable: Iterable<T> | AsyncIterable<T>
7, fn: (element: Awaited<T>, index: number) => Awaitable<U>
8): AsyncIterableIterator<Awaited<U>>

1map([1, 2, 3], x => x * 2) // [2, 4, 6]

flatMap, flatMapAsync

1function flatMap<T, U>(
2  iterable: Iterable<T>
3, fn: (element: T, index: number) => Iterable<U>
4): IterableIterator<U>
5function flatMapAsync<T, U>(
6  iterable: Iterable<T> | AsyncIterable<T>
7, fn: (element: Awaited<T>, index: number) => Awaitable<Iterable<U> | AsyncIterable<U>>
8): AsyncIterableIterator<Awaited<U>>

1map([1, 2, 3], x => [x, x * 2]) // [1, 2, 2, 4, 3, 6]

repeat, repeatAsync

1function repeat<T>(
2  iterable: Iterable<T>
3, times: number // times >= 0
4): IterableIterator<T>
5function repeatAsync<T>(
6  iterable: AsyncIterable<T>
7, times: number // times >= 0
8): AsyncIterableIterator<Awaited<T>>

1repeat([1, 2, 3], 2) // [1, 2, 3, 1, 2, 3]
2repeat([1, 2, 3], 0) // []
3repeat([1, 2, 3], -1) // throw Error

The memory usage of this function depends on iterable.

slice, sliceAsync

1function slice<T>(
2  iterable: Iterable<T>
3, start: number // start >= 0
4, end: number = Infinity // end >= start
5): IterableIterator<T>
6function sliceAsync<T>(
7  iterable: AsyncIterable<T>
8, start: number // start >= 0
9, end: number = Infinity // end >= start
10): AsyncIterableIterator<Awaited<T>>

1slice([1, 2, 3], -1, 1) // throw Error
2slice([1, 2, 3], 3, 5) // []
3slice([1, 2, 3], 1, 2) // [2]
4slice([1, 2, 3], 1, 1) // []
5slice([1, 2, 3], 2, 1) // throw Error

join, joinAsync

1function join<T, U = T>(iterable: Iterable<T>, separator: U): IterableIterator<T | U>
2function joinAsync<T, U = T>(
3  iterable: AsyncIterable<T>
4, separator: U
5): AsyncIterableIterator<Awaited<T> | U>

1join([1, 2, 3], '+') // [1, '+', 2, '+', 3]

split, splitAsync

1function split<T>(iterable: Iterable<T>, separator: T): IterableIterator<T[]>
2function splitAsync<T>(
3  iterable: AsyncIterable<T>
4, separator: T
5): AsyncIterableIterator<Array<Awaited<T>>>

1split([1, 2, 3, 4, 5], 3) // [[1, 2], [4, 5]]
2split([1, 2, 3, 4, 5], 1) // [[], [2, 3, 4, 5]]
3split([1, 2, 3, 4, 5], 5) // [[1, 2, 3, 4], []]
4split([1, 2, 3, 4, 5], 0) // [[1, 2, 3, 4, 5]]

The memory usage of this function depends on iterable and separator.

splitBy, splitByAsync

1function splitBy<T>(
2  iterable: Iterable<T>
3, predicate: (element: T, index: number) => unknown
4): IterableIterator<T[]>
5function splitByAsync<T>(
6  iterable: Iterable<T> | AsyncIterable<T>
7, predicate: (element: Awaited<T>, index: number) => Awaitable<unknown>
8): AsyncIterableIterator<Array<Awaited<T>>>

1splitBy([1, 2, 3, 4, 5], x => x === 3) // [[1, 2], [4, 5]]
2splitBy([1, 2, 3, 4, 5], x => x === 1) // [[], [2, 3, 4, 5]]
3splitBy([1, 2, 3, 4, 5], x => x === 5) // [[1, 2, 3, 4], []]
4splitBy([1, 2, 3, 4, 5], x => x === 0) // [[1, 2, 3, 4, 5]]

The memory usage of this function depends on iterable and predicate.

take, takeAsync

1function take<T>(iterable: Iterable<T>, count: number): IterableIterator<T>
2function takeAsync<T>(
3  iterable: AsyncIterable<T>
4, count: number
5): AsyncIterableIterator<Awaited<T>>

1take([1, 2, 3], 5) // [1, 2, 3]
2take([1, 2, 3], 2) // [1, 2]
3take([1, 2, 3], 0) // []
4take([1, 2, 3], -1) // throw Error

takeRight, takeRightAsync

1function takeRight<T>(iterable: Iterable<T>, count: number): IterableIterator<T>
2function takeRightAsync<T>(
3  iterable: AsyncIterable<T>
4, count: number
5): AsyncIterableIterator<Awaited<T>>

1takeRight([1, 2, 3], 2) // [2, 3]
2takeRight([1, 2, 3], 5) // [1, 2, 3]
3takeRight([1, 2, 3], 0) // []
4takeRight([1, 2, 3], -1) // throw Error

The memory usage of this function depends on count.

takeUntil, takeUntilAsync

1function takeUntil<T>(
2  iterable: Iterable<T>
3, predicate: (element: T, index: number) => unknown
4): IterableIterator<T>
5function takeUntilAsync<T>(
6  iterable: Iterable<T> | AsyncIterable<T>
7, predicate: (element: Awaited<T>, index: number) => Awaitable<unknown>
8): AsyncIterableIterator<Awaited<T>>

1takeUntil([1, 2, 3], x => x === 2) // [1]

tap, tapAsync

1function tap<T>(
2  iterable: Iterable<T>
3, fn: (element: T, index: number) => unknown
4): IterableIterator<T>
5function tapAsync<T>(
6  iterable: Iterable<T> | AsyncIterable<T>
7, fn: (element: Awaited<T>, index: number) => Awaitable<unknown>
8): AsyncIterableIterator<Awaited<T>>

1tap([1, 2, 3], x => console.log(x)) // [1, 2, 3]

toAsyncIterable

1function toAsyncIterable<T>(
2  iterable: Iterable<Awaitable<T>>
3): AsyncIterableIterator<Awaited<T>>

1toAsyncIterable([1, 2, 3]) // AsyncIterable [1, 2, 3]

transform, transformAsync

1function transform<T, U>(
2  iterable: Iterable<T>
3, transformer: (iterable: Iterable<T>) => Iterable<U>
4): IterableIterator<U>
5function transformAsync<T, U>(
6  iterable: Iterable<T>
7, transformer: (iterable: Iterable<T>) => AsyncIterable<U>
8): AsyncIterableIterator<Awaited<U>>
9function transformAsync<T, U>(
10  iterable: AsyncIterable<T>
11, transformer: (iterable: AsyncIterable<T>) => AsyncIterable<U>
12): AsyncIterableIterator<Awaited<U>>

1transform([1, 2, 3], function* double(iter) {
2  for (const element of iter) {
3    yield element * 2
4  }
5}) // [2, 4, 6]

uniq, uniqAsync

1function uniq<T>(iterable: Iterable<T>): IterableIterator<T>
2function uniqAsync<T>(iterable: AsyncIterable<T>): AsyncIterableIterator<Awaited<T>>

1uniq([1, 1, 2, 2, 3, 3]) // [1, 2, 3]

The memory usage of this function depends on iterable.

uniqBy, uniqByAsync

1function uniqBy<T, U>(
2  iterable: Iterable<T>
3, fn: (element: T, index: number) => U
4): IterableIterator<T>
5function uniqByAsync<T, U>(
6  iterable: Iterable<T> | AsyncIterable<T>
7, fn: (element: Awaited<T>, index: number) => Awaitable<U>
8): AsyncIterableIterator<Awaited<T>>

1uniqBy([1, 2, 3], x => x % 2) // [1, 2]

The memory usage of this function depends on fn.

zip, zipAsync

1function zip<T, U extends Array<Iterable<unknown>>>(
2  iterable: Iterable<T>
3, ...otherIterables: U
4): IterableIterator<[T, ...ExtractTypeTupleFromIterableTuple<U>]>
5function zipAsync<
6  T
7, U extends Array<Iterable<Awaitable<unknown>> | AsyncIterable<Awaitable<unknown>>>
8>(
9  iterable: Iterable<Awaitable<T>> | AsyncIterable<Awaitable<T>>
10, ...otherIterables: U
11): AsyncIterableIterator<
12  [Awaited<T>, ...ExtractTypeTupleFromAsyncLikeIterableTuple<U>]
13>

1zip([1, 2, 3], ['a', 'b', 'c']) // [[1, 'a'], [2, 'b'], [3, 'c']]
2zip([1, 2, 3], ['a', 'b']) // [[1, 'a'], [2, 'b']
3zip([1, 2, 3], ['a', 'b'], ['i', 'ii', 'iii']) // [[1, 'a', 'i'], [2, 'b', 'ii']]

consume, consumerAsync

1function consume<T, U>(iterable: Iterable<T>, consumer: (iterable: Iterable<T>) => U): U
2function consumeAsync<T, U>(
3  iterable: Iterable<T>
4, consumer: (iterable: Iterable<T>) => Awaitable<U>
5): Promise<Awaited<U>>
6function consumeAsync<T, U>(
7  iterable: AsyncIterable<T>
8, consumer: (iterable: AsyncIterable<T>) => Awaitable<U>
9): Promise<Awaited<U>>

1consume([1, 2, 3], xs => new Set(xs)) // Set [1, 2, 3]

each, eachAsync

1function each<T>(
2  iterable: Iterable<T>
3, fn: (element: T, index: number) => unknown
4): void
5function eachAsync<T>(
6  iterable: Iterable<T> | AsyncIterable<T>
7, fn: (element: Awaited<T>, index: number) => Awaitable<unknown>
8): Promise<void>

1each([1, 2, 3], x => console.log(x)) // void

every, everyAsync

1function every<T>(
2  iterable: Iterable<T>
3, predicate: (element: T, index: number) => unknown
4): boolean
5function everyAsync<T>(
6  iterable: Iterable<T> | AsyncIterable<T>
7, predicate: (element: Awaited<T>, index: number) => Awaitable<unknown>
8): Promise<boolean>

1every([1, 2, 3], x => x < 5) // true
2every([1, 2, 3], x => x <= 2) // false

find, findAsync

1function find<T>(
2  iterable: Iterable<T>
3, predicate: (element: T, index: number) => unknown
4): T | undefined
5function findAsync<T>(
6  iterable: Iterable<T> | AsyncIterable<T>
7, predicate: (element: Awaited<T>, index: number) => Awaitable<unknown>
8): Promise<Awaited<T> | undefined>

1find([1, 2, 3], x => x === 2) // 2
2find([1, 2, 3], x => x === 4) // undefined

findAllIndexes

1function findAllIndexes<T>(
2  iterable: Iterable<T>
3, predicate: (value: T, index: number) => unknown
4): IterableIterator<number>

1findAllIndexes([1, 2, 3], x => x % 2 === 1) // [0, 2]

first, firstAsync

1function first<T>(iterable: Iterable<T>): T | undefined
2function firstAsync<T>(iterable: AsyncIterable<T>): Promise<Awaited<T> | undefined>

1first([1, 2, 3]) // 1
2first([]) // undefined

includes, includesAsync

1function includes<T>(iterable: Iterable<T>, value: T): boolean
2function includesAsync<T>(
3  iterable: AsyncIterable<T>
4, value: Awaited<T>
5): Promise<boolean>

1includes([1, 2, 3], 2) // true
2includes([1, 2, 3], 4) // false

last, lastAsync

1function last<T>(iterable: Iterable<T>): T | undefined
2function lastAsync<T>(iterable: AsyncIterable<T>): Promise<Awaited<T> | undefined>

1last([1, 2, 3]) // 3
2last([]) // undefined

reduce, reduceAsync

1function reduce<T>(
2  iterable: Iterable<T>
3, fn: (accumulator: T, currentValue: T, index: number) => T
4): T
5function reduce<T, U>(
6  iterable: Iterable<T>
7, fn: (accumulator: U, currentValue: T, index: number) => U
8, initialValue: U
9): U
10function reduceAsync<T>(
11  iterable: Iterable<T> | AsyncIterable<T>
12, fn: (
13    accumulator: Awaited<T>
14  , currentValue: Awaited<T>
15  , index: number
16  ) => Awaitable<Awaited<T>>
17): Promise<Awaited<T>>
18function reduceAsync<T, U>(
19  iterable: Iterable<T> | AsyncIterable<T>
20, fn: (accumulator: Awaited<U>, currentValue: Awaited<T>, index: number) => Awaitable<U>
21, initialValue: U
22): Promise<Awaited<U>>

1reduce([], (acc, cur) => acc + cur) // throw Error
2reduce([1], (acc, cur) => acc + cur) // 1
3reduce([1, 2, 3], (acc, cur) => acc + cur) // 6
4
5reduce([1, 2, 3], (acc, cur, index) => {
6  acc.push([cur, index])
7  return acc
8}) // [[1, 0], [2, 1], [3, 2]]

some, someAsync

1function some<T>(
2  iterable: Iterable<T>
3, predicate: (element: T, index: number) => unknown
4): boolean
5function someAsync<T>(
6  iterable: Iterable<T> | AsyncIterable<T>
7, predicate: (element: Awaited<T>, index: number) => Awaitable<unknown>
8): Promise<boolean>

1some([1, 2, 3], x => x === 2) // true
2some([1, 2, 3], x => x === 4) // false

toArray, toArrayAsync

1function toArray<T>(iterable: Iterable<T>): T[]
2function toArrayAsync<T>(
3  iterable: AsyncIterable<T>
4): Promise<Array<Awaited<T>>>

1toArray([1, 2, 3]) // Array [1, 2, 3]

toSet, toSetAsync

1function toSet<T>(iterable: Iterable<T>): Set<T>
2function toSetAsync<T>(
3  iterable: Iterable<T> | AsyncIterable<T>
4): Promise<Set<Awaited<T>>>

1toSet([1, 1, 2, 2, 3, 3]) // Set [1, 2, 3]

count, countAsync

1function count(iterable: Iterable<unknown>): number
2function countAsync(iterable: AsyncIterable<unknown>): Promise<number>

1count([1, 2, 3]) // 3

groupBy, groupByAsync

1function groupBy<T, U>(
2  iterable: Iterable<T>
3, fn: (element: T, index: number) => U
4): Map<U, T[]>
5function groupByAsync<T, U>(
6  iterable: Iterable<T> | AsyncIterable<T>
7, fn: (element: Awaited<T>, index: number) => Awaitable<U>
8): Promise<Map<Awaited<U>, Array<Awaited<T>>>>

1groupBy([1, 2, 3], x => x % 2) // { 1: [1, 3], 0: [2] }

prefetch, prefetchAsync

1function prefetch<T>(iterable: Iterable<T>, size: number): AsyncIterableIterator<T>
2function prefetchAsync<T>(
3  iterable: AsyncIterable<T>
4, size: number
5): AsyncIterableIterator<T>

top, topAsync

1function top<T>(
2  iterable: Iterable<T>
3, num: number
4, compare: (a: T, b: T) => number
5): T[]
6function topAsync<T>(
7  iterable: AsyncIterable<T>
8, num: number
9, compare: (a: Awaited<T>, b: Awaited<T>) => number
10): Promise<Array<Awaited<T>>>

1top([1, 2, 3], 2, (a, b) => b - a) // [3, 2]

avg, avgAsync

1function avg(iterable: Iterable<number>): number
2function avgAsync(iterable: AsyncIterable<number>): Promise<number>

1avg([1, 2, 3]) // 2