iterable-operator

iterable-operator

Utilities for JavaScript Iterable and AsyncIterable.

Install

npm install --save iterable-operator
# or
yarn add iterable-operator

Usage

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.

API

isIterable

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

isAsyncIterable

function isAsyncIterable<T>(val: unknown): val is AsyncIterable<T>
function isntAsyncIterable<T>(
  val: T
): val is Exclude<T, AsyncIterable<unknown>>

chunk, chunkAsync

function chunk<T>(
  iterable: Iterable<T>
, size: number // size > 0
): IterableIterator<T[]>
function chunkAsync<T>(
  iterable: AsyncIterable<T>
, size: number // size > 0
): AsyncIterableIterator<Array<Awaited<T>>>

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 size.

chunkBy, chunkByAsync

function chunkBy<T>(
  iterable: Iterable<T>
, predicate: (element: T, index: number) => unknown
): IterableIterator<T[]>
function chunkByAsync<T>(
  iterable: Iterable<T> | AsyncIterable<T>
, predicate: (element: Awaited<T>, index: number) => Awaitable<unknown>
): AsyncIterableIterator<Array<Awaited<T>>>

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 iterable and predicate.

concat, concatAsync

function concat<T, U>(
  iterable: Iterable<T>
, ...otherIterables: Iterable<U>[]
): IterableIterator<T | U>
function concatAsync<T, U>(
  iterable: Iterable<T> | AsyncIterable<T>
, ...otherIterables: Array<Iterable<Awaitable<U>> | AsyncIterable<Awaitable<U>>>
): AsyncIterableIterator<Awaited<T> | Awaited<U>>

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

difference, differenceAsync

function difference<T>(left: Iterable<T>, right: Iterable<T>): IterableIterator<T>
function differenceAsync<T>(
  left: Iterable<Awaitable<T>> | AsyncIterable<Awaitable<T>>
, right: Iterable<Awaitable<T>> | AsyncIterable<Awaitable<T>>
): AsyncIterableIterator<Awaited<T>>

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

The memory usage of this function depends on right.

drop, dropAsync

function drop<T>(
  iterable: Iterable<T>
, count: number // count >= 0
): IterableIterator<T>
function dropAsync<T>(
  iterable: AsyncIterable<T>
, count: number // count >= 0
): AsyncIterableIterator<Awaited<T>>

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

dropRight, dropRightAsync

function dropRight<T>(
  iterable: Iterable<T>
, count: number // count >= 0
): IterableIterator<T>
function dropRightAsync<T>(
  iterable: AsyncIterable<T>
, count: number // count >= 0
): AsyncIterableIterator<Awaited<T>>

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 iterable.

dropUntil, dropUntilAsync

function dropUntil<T>(
  iterable: Iterable<T>
, predicate: (element: T, index: number) => unknown
): IterableIterator<T>
function dropUntilAsync<T>(
  iterable: Iterable<T> | AsyncIterable<T>
, predicate: (element: Awaited<T>, index: number) => Awaitable<unknown>
): AsyncIterableIterator<Awaited<T>>

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

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

filter, filterAsync

function filter<T, U extends T = T>(
  iterable: Iterable<T>
, predicate: (element: T, index: number) => unknown
): IterableIterator<U>
function filterAsync<T, U extends Awaited<T> = Awaited<T>>(
  iterable: Iterable<T> | AsyncIterable<T>
, predicate: (element: Awaited<T>, index: number) => Awaitable<unknown>
): AsyncIterableIterator<U>

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

flatten, flattenAsync

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

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

flattenDeep, flattenDeepAsync

function flattenDeep<T>(
  iterable: Iterable<unknown>
, depth: number = Infinity // depth >= 0
): IterableIterator<T>
function flattenDeepAsync<T>(
  iterable: AsyncIterable<unknown>
, depth: number = Infinity // depth >= 0
): AsyncIterableIterator<T>

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]]

flattenBy, flattenByAsync

function flattenBy<T>(
  iterable: Iterable<unknown>
, predicate: (element: unknown, level: number) => boolean
): IterableIterator<T>
function flattenByAsync<T>(
  iterable: Iterable<unknown> | AsyncIterable<unknown>
, predicate: (element: unknown, level: number) => Awaitable<unknown>
): AsyncIterableIterator<T>

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

intersection, intersectionAsync

function intersection<T>(left: Iterable<T>, right: Iterable<T>): IterableIterator<T>
function intersectionAsync<T>(
  left: Iterable<Awaitable<T>> | AsyncIterable<T>
, right: Iterable<Awaitable<T>> | AsyncIterable<T>
): AsyncIterableIterator<Awaited<T>>

The memory usage of this function depends on right.

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

map, mapAsync

function map<T, U>(
  iterable: Iterable<T>
, fn: (element: T, index: number) => U
): IterableIterator<U>
function mapAsync<T, U>(
  iterable: Iterable<T> | AsyncIterable<T>
, fn: (element: Awaited<T>, index: number) => Awaitable<U>
): AsyncIterableIterator<Awaited<U>>

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

flatMap, flatMapAsync

function flatMap<T, U>(
  iterable: Iterable<T>
, fn: (element: T, index: number) => Iterable<U>
): IterableIterator<U>
function flatMapAsync<T, U>(
  iterable: Iterable<T> | AsyncIterable<T>
, fn: (element: Awaited<T>, index: number) => Awaitable<Iterable<U> | AsyncIterable<U>>
): AsyncIterableIterator<Awaited<U>>

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

repeat, repeatAsync

function repeat<T>(
  iterable: Iterable<T>
, times: number // times >= 0
): IterableIterator<T>
function repeatAsync<T>(
  iterable: AsyncIterable<T>
, times: number // times >= 0
): AsyncIterableIterator<Awaited<T>>

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 iterable.

slice, sliceAsync

function slice<T>(
  iterable: Iterable<T>
, start: number // start >= 0
, end: number = Infinity // end >= start
): IterableIterator<T>
function sliceAsync<T>(
  iterable: AsyncIterable<T>
, start: number // start >= 0
, end: number = Infinity // end >= start
): AsyncIterableIterator<Awaited<T>>

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

join, joinAsync

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

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

split, splitAsync

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

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 iterable and separator.

splitBy, splitByAsync

function splitBy<T>(
  iterable: Iterable<T>
, predicate: (element: T, index: number) => unknown
): IterableIterator<T[]>
function splitByAsync<T>(
  iterable: Iterable<T> | AsyncIterable<T>
, predicate: (element: Awaited<T>, index: number) => Awaitable<unknown>
): AsyncIterableIterator<Array<Awaited<T>>>

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 iterable and predicate.

take, takeAsync

function take<T>(iterable: Iterable<T>, count: number): IterableIterator<T>
function takeAsync<T>(
  iterable: AsyncIterable<T>
, count: number
): AsyncIterableIterator<Awaited<T>>

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

takeRight, takeRightAsync

function takeRight<T>(iterable: Iterable<T>, count: number): IterableIterator<T>
function takeRightAsync<T>(
  iterable: AsyncIterable<T>
, count: number
): AsyncIterableIterator<Awaited<T>>

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 count.

takeUntil, takeUntilAsync

function takeUntil<T>(
  iterable: Iterable<T>
, predicate: (element: T, index: number) => unknown
): IterableIterator<T>
function takeUntilAsync<T>(
  iterable: Iterable<T> | AsyncIterable<T>
, predicate: (element: Awaited<T>, index: number) => Awaitable<unknown>
): AsyncIterableIterator<Awaited<T>>

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

tap, tapAsync

function tap<T>(
  iterable: Iterable<T>
, fn: (element: T, index: number) => unknown
): IterableIterator<T>
function tapAsync<T>(
  iterable: Iterable<T> | AsyncIterable<T>
, fn: (element: Awaited<T>, index: number) => Awaitable<unknown>
): AsyncIterableIterator<Awaited<T>>

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

toAsyncIterable

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

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

transform, transformAsync

function transform<T, U>(
  iterable: Iterable<T>
, transformer: (iterable: Iterable<T>) => Iterable<U>
): IterableIterator<U>
function transformAsync<T, U>(
  iterable: Iterable<T>
, transformer: (iterable: Iterable<T>) => AsyncIterable<U>
): AsyncIterableIterator<Awaited<U>>
function transformAsync<T, U>(
  iterable: AsyncIterable<T>
, transformer: (iterable: AsyncIterable<T>) => AsyncIterable<U>
): AsyncIterableIterator<Awaited<U>>

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

uniq, uniqAsync

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

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

The memory usage of this function depends on iterable.

uniqBy, uniqByAsync

function uniqBy<T, U>(
  iterable: Iterable<T>
, fn: (element: T, index: number) => U
): IterableIterator<T>
function uniqByAsync<T, U>(
  iterable: Iterable<T> | AsyncIterable<T>
, fn: (element: Awaited<T>, index: number) => Awaitable<U>
): AsyncIterableIterator<Awaited<T>>

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

The memory usage of this function depends on fn.

zip, zipAsync

function zip<T, U extends Array<Iterable<unknown>>>(
  iterable: Iterable<T>
, ...otherIterables: U
): IterableIterator<[T, ...ExtractTypeTupleFromIterableTuple<U>]>
function zipAsync<
  T
, U extends Array<Iterable<Awaitable<unknown>> | AsyncIterable<Awaitable<unknown>>>
>(
  iterable: Iterable<Awaitable<T>> | AsyncIterable<Awaitable<T>>
, ...otherIterables: U
): AsyncIterableIterator<
  [Awaited<T>, ...ExtractTypeTupleFromAsyncLikeIterableTuple<U>]
>

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']]

consume, consumerAsync

function consume<T, U>(iterable: Iterable<T>, consumer: (iterable: Iterable<T>) => U): U
function consumeAsync<T, U>(
  iterable: Iterable<T>
, consumer: (iterable: Iterable<T>) => Awaitable<U>
): Promise<Awaited<U>>
function consumeAsync<T, U>(
  iterable: AsyncIterable<T>
, consumer: (iterable: AsyncIterable<T>) => Awaitable<U>
): Promise<Awaited<U>>

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

each, eachAsync

function each<T>(
  iterable: Iterable<T>
, fn: (element: T, index: number) => unknown
): void
function eachAsync<T>(
  iterable: Iterable<T> | AsyncIterable<T>
, fn: (element: Awaited<T>, index: number) => Awaitable<unknown>
): Promise<void>

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

every, everyAsync

function every<T>(
  iterable: Iterable<T>
, predicate: (element: T, index: number) => unknown
): boolean
function everyAsync<T>(
  iterable: Iterable<T> | AsyncIterable<T>
, predicate: (element: Awaited<T>, index: number) => Awaitable<unknown>
): Promise<boolean>

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

find, findAsync

function find<T>(
  iterable: Iterable<T>
, predicate: (element: T, index: number) => unknown
): T | undefined
function findAsync<T>(
  iterable: Iterable<T> | AsyncIterable<T>
, predicate: (element: Awaited<T>, index: number) => Awaitable<unknown>
): Promise<Awaited<T> | undefined>

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

findAllIndexes

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

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

first, firstAsync

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

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

includes, includesAsync

function includes<T>(iterable: Iterable<T>, value: T): boolean
function includesAsync<T>(
  iterable: AsyncIterable<T>
, value: Awaited<T>
): Promise<boolean>

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

last, lastAsync

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

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

reduce, reduceAsync

function reduce<T>(
  iterable: Iterable<T>
, fn: (accumulator: T, currentValue: T, index: number) => T
): T
function reduce<T, U>(
  iterable: Iterable<T>
, fn: (accumulator: U, currentValue: T, index: number) => U
, initialValue: U
): U
function reduceAsync<T>(
  iterable: Iterable<T> | AsyncIterable<T>
, fn: (
    accumulator: Awaited<T>
  , currentValue: Awaited<T>
  , index: number
  ) => Awaitable<Awaited<T>>
): Promise<Awaited<T>>
function reduceAsync<T, U>(
  iterable: Iterable<T> | AsyncIterable<T>
, fn: (accumulator: Awaited<U>, currentValue: Awaited<T>, index: number) => Awaitable<U>
, initialValue: U
): Promise<Awaited<U>>

reduce([], (acc, cur) => acc + cur) // throw Error
reduce([1], (acc, cur) => acc + cur) // 1
reduce([1, 2, 3], (acc, cur) => acc + cur) // 6

reduce([1, 2, 3], (acc, cur, index) => {
  acc.push([cur, index])
  return acc
}) // [[1, 0], [2, 1], [3, 2]]

some, someAsync

function some<T>(
  iterable: Iterable<T>
, predicate: (element: T, index: number) => unknown
): boolean
function someAsync<T>(
  iterable: Iterable<T> | AsyncIterable<T>
, predicate: (element: Awaited<T>, index: number) => Awaitable<unknown>
): Promise<boolean>

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

toArray, toArrayAsync

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

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

toSet, toSetAsync

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

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

count, countAsync

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

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

groupBy, groupByAsync

function groupBy<T, U>(
  iterable: Iterable<T>
, fn: (element: T, index: number) => U
): Map<U, T[]>
function groupByAsync<T, U>(
  iterable: Iterable<T> | AsyncIterable<T>
, fn: (element: Awaited<T>, index: number) => Awaitable<U>
): Promise<Map<Awaited<U>, Array<Awaited<T>>>>

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

prefetch, prefetchAsync

function prefetch<T>(iterable: Iterable<T>, size: number): AsyncIterableIterator<T>
function prefetchAsync<T>(
  iterable: AsyncIterable<T>
, size: number
): AsyncIterableIterator<T>

top, topAsync

function top<T>(
  iterable: Iterable<T>
, num: number
, compare: (a: T, b: T) => number
): T[]
function topAsync<T>(
  iterable: AsyncIterable<T>
, num: number
, compare: (a: Awaited<T>, b: Awaited<T>) => number
): Promise<Array<Awaited<T>>>

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

avg, avgAsync

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

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

Changelog

5.1.0 (2024-04-20)

Features

• add avg, avgAsync (36abff9)