Have ideas to improve npm?Join in the discussion! »

    iterable-operator
    TypeScript icon, indicating that this package has built-in type declarations

    0.13.6 • Public • Published

    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)

    Chaining

    import { IterableOperator } from 'iterable-operator/lib/es2018/style/chaining'
    
    const result = new IterableOperator([1, 2, 3])
      .map(x => x * 2)
      .toArray()

    Binding

    It is prepared for bind-operator.

    import { map, toArray } from 'iterable-operator/lib/es2018/style/binding'
    
    const result = [1, 2, 3]
      ::map(x => x * 2)
      ::toArray()

    Pipeline

    It is prepared for pipeline-operator.

    import { map, toArray } from 'iterable-operator/lib/es2018/style/pipeline'
    
    const result = [1, 2, 3]
      |> map(x => x * 2)
      |> toArray()

    API

    There are two kinds of operators:

    • Intermediate operation(middleware): lazy, the first parameter is Iterable, the return value is Iterable(Iterable in, Iterable out)
    • Terminal operation(output): the first parameter is Iterable

    Middleware

    chunk, chunkAsync

    function chunk<T>(iterable: Iterable<T>, size: number): Iterable<T[]>
    function chunkAsync<T>(iterable: AsyncIterable<T>, size: number): AsyncIterable<T[]>
    // size > 0
    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 InvalidArgumentError
    chunk([1, 2, 3], -1) // throw InvalidArgumentError

    chunkBy, chunkBy

    function chunkBy<T>(iterable: Iterable<T>, predicate: (element: T, index: number) => unknown): Iterable<T[]>
    function chunkByAsync<T>(iterable: Iterable<T> | AsyncIterable<T>, predicate: (element: T, index: number) => unknown | PromiseLike<unknown>): AsyncIterable<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]]

    concat, concatAsync

    function concat<T, U>(iterable: Iterable<T>, ...otherIterables: Iterable<U>[]): Iterable<T | U> {
    function concatAsync<T, U>(
      iterable: Iterable<T | PromiseLike<T>> | AsyncIterable<T>
    , ...otherIterables: Array<Iterable<U | PromiseLike<U>> | AsyncIterable<U>>
    ): AsyncIterable<T | U> {
    concat([1, 2, 3]) // [1, 2, 3]
    concat([1, 2, 3], ['a', 'b', 'c']) // [1, 2, 3, 'a', 'b', 'c']

    drop, dropAsync

    function drop<T>(iterable: Iterable<T>, count: number): Iterable<T>
    function dropAsync<T>(iterable: AsyncIterable<T>, count: number): AsyncIterable<T>
    // count >= 0
    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 InvalidArgumentError

    dropRight, dropRightAsync

    function dropRight<T>(iterable: Iterable<T>, count: number): Iterable<T>
    function dropRightAsync<T>(iterable: AsyncIterable<T>, count: number): AsyncIterable<T>
    // count >= 0
    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 InvalidArgumentError

    dropUntil, dropUntilAsync

    function dropUntil<T>(iterable: Iterable<T>, predicate: (element: T, index: number) => unknown): Iterable<T>
    function dropUntilAsync<T>(iterable: Iterable<T> | AsyncIterable<T>, predicate: (element: T, index: number) => boolean | PromiseLike<boolean>): AsyncIterable<T>
    dropUntil([1, 2, 3], x => x === 2) // [2, 3]

    filter, filterAsync

    function filter<T, U extends T = T>(iterable: Iterable<T>, predicate: (element: T, index: number) => unknown): Iterable<U>
    function filterAsync<T, U extends T = T>(iterable: Iterable<T> | AsyncIterable<T>, predicate: (element: T, index: number) => unknown | PromiseLike<unknown>): AsyncIterable<U>
    filter([1, 2, 3], x => x % 2 === 1) // [1, 3]

    flatten, flattenAsync

    function flatten<T>(iterable: Iterable<unknown>): Iterable<T>
    function flattenAsync<T>(iterable: AsyncIterable<unknown>): AsyncIterable<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): Iterable<T>
    function flattenDeepAsync<T>(iterable: AsyncIterable<unknown>, depth: number = Infinity): AsyncIterable<T>
    // depth >= 0
    flattenDeep([]) // []
    flattenDeep('123') // ['1', '2', '3']
    flattenDeep([], -1) // throw InvalidArgumentError
    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): Iterable<T>
    function flattenByAsync<T>(iterable: Iterable<unknown> | AsyncIterable<unknown>, predicate: (element: unknown, level: number) => boolean | PromiseLike<unknown>): AsyncIterable<T>
    flattenBy(['one', ['two'], 0, [1]], x => typeof x !== 'string') // ['one', 'two', 0, 1]
    flattenBy([], () => true) // []
    flattenBy('123', () => true) // ['1', '2', '3']

    map, mapAsync

    function map<T, U>(iterable: Iterable<T>, fn: (element: T, index: number) => U): Iterable<U>
    function mapAsync<T, U>(iterable: Iterable<T> | AsyncIterable<T>, fn: (element: T, index: number) => U | PromiseLike<U>): AsyncIterable<U>
    map([1, 2, 3], x => x * 2) // [2, 4, 6]

    repeat, repeatAsync

    function repeat<T>(iterable: Iterable<T>, times: number): Iterable<T>
    function repeatAsync<T>(iterable: AsyncIterable<T>, times: number): AsyncIterable<T>
    // times >= 0
    repeat([1, 2, 3], 2) // [1, 2, 3, 1, 2, 3]
    repeat([1, 2, 3], 0) // []
    repeat([1, 2, 3], -1) // throw InvalidArgumentError

    slice, sliceAsync

    function slice<T>(iterable: Iterable<T>, start: number, end: number = Infinity): Iterable<T>
    function sliceAsync<T>(iterable: AsyncIterable<T>, start: number, end: number = Infinity): AsyncIterable<T>
    // start >= 0, end >= start
    slice([1, 2, 3], -1, 1) // throw InvalidArgumentError
    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 InvalidArgumentError

    split, splitAsync

    function split<T>(iterable: Iterable<T>, separator: T): Iterable<T[]>
    function splitAsync<T>(iterable: AsyncIterable<T>, separator: T): AsyncIterable<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]]

    splitBy, splitByAsync

    function splitBy<T>(iterable: Iterable<T>, predicate: (element: T, index: number) => unknown): Iterable<T[]>
    function splitByAsync<T>(iterable: Iterable<T> | AsyncIterable<T>, predicate: (element: T, index: number) => unknown | PromiseLike<unknown>): AsyncIterable<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]]

    take, takeAsync

    function take<T>(iterable: Iterable<T>, count: number): Iterable<T>
    function takeAsync<T>(iterable: AsyncIterable<T>, count: number): AsyncIterable<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 InvalidArgumentError

    takeRight, takeRightAsync

    function takeRight<T>(iterable: Iterable<T>, count: number): Iterable<T>
    function takeRightAsync<T>(iterable: AsyncIterable<T>, count: number): AsyncIterable<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 InvalidArgumentError

    takeUntil, takeUntilAsync

    function takeUntil<T>(iterable: Iterable<T>, predicate: (element: T, index: number) => unknown): Iterable<T>
    function takeUntilAsync<T>(iterable: Iterable<T> | AsyncIterable<T>, predicate: (element: T, index: number) => unknown | PromiseLike<unknown>): AsyncIterable<T>
    takeUntil([1, 2, 3], x => x === 2) // [1]

    tap, tapAsync

    function tap<T>(iterable: Iterable<T>, fn: (element: T, index: number) => unknown): Iterable<T> {
    function tapAsync<T>(iterable: Iterable<T> | AsyncIterable<T>, fn: (element: T, index: number) => unknown | PromiseLike<unknown>): AsyncIterable<T>
    tap([1, 2, 3], x => console.log(x)) // [1, 2, 3]

    toAsyncIterable

    function toAsyncIterable<T>(iterable: Iterable<T | PromiseLike<T>>): AsyncIterable<T>
    toAsyncIterable([1, 2, 3]) // AsyncIterable [1, 2, 3]

    transform, transformAsync

    function transform<T, U>(iterable: Iterable<T>, transformer: (iterable: Iterable<T>) => Iterable<U>): Iterable<U>
    function transformAsync<T, U>(iterable: Iterable<T>, transformer: (iterable: Iterable<T>) => AsyncIterable<U>): AsyncIterable<U>
    function transformAsync<T, U>(iterable: AsyncIterable<T>, transformer: (iterable: AsyncIterable<T>) => AsyncIterable<U>): AsyncIterable<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>): Iterable<T>
    function uniqAsync<T>(iterable: AsyncIterable<T>): AsyncIterable<T>
    uniq([1, 1, 2, 2, 3, 3]) // [1, 2, 3]

    uniqBy, uniqByAsync

    function uniqBy<T, U>(iterable: Iterable<T>, fn: (element: T, index: number) => U): Iterable<T> {
    function uniqByAsync<T, U>(iterable: Iterable<T> | AsyncIterable<T>, fn: (element: T, index: number) => U | PromiseLike<U>): AsyncIterable<T>
    uniqBy([1, 2, 3], x => x % 2) // [1, 2]

    zip, zipAsync

    function zip<T, U extends Array<Iterable<unknown>>>(
      iterable: Iterable<T>
    , ...otherIterables: U
    ): Iterable<[T, ...ExtractTypeTupleFromIterableTuple<U>]> {
    function zipAsync<T, U extends Array<Iterable<unknown> | AsyncIterable<unknown>>>(
      iterable: Iterable<T | PromiseLike<T>> | AsyncIterable<T>
    , ...otherIterables: U
    ): AsyncIterable<[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']]

    Output

    consume

    function consume<T, U>(iterable: Iterable<T>, consumer: (iterable: Iterable<T>) => U): U
    function consume<T, U>(iterable: AsyncIterable<T>, consumer: (iterable: AsyncIterable<T>) => U): 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: T, index: number) => unknown | PromiseLike<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: T, index: number) => unknown | PromiseLike<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
    function findAsync<T>(iterable: Iterable<T> | AsyncIterable<T>, predicate: (element: T, index: number) => unknown | PromiseLike<unknown>): Promise<T>
    find([1, 2, 3], x => x === 2) // 2
    find([1, 2, 3], x => x === 4) // throw RuntimeError

    first, firstAsync

    function first<T>(iterable: Iterable<T>): T
    function firstAsync<T>(iterable: AsyncIterable<T>): Promise<T>
    first([1, 2, 3]) // 1
    first([]) // throw RuntimeError

    includes, includesAsync

    function includes<T>(iterable: Iterable<T>, value: T): boolean
    function includesAsync<T>(iterable: AsyncIterable<T>, value: T): Promise<boolean>
    includes([1, 2, 3], 2) // true
    includes([1, 2, 3], 4) // false

    last, lastAsync

    function last<T>(iterable: Iterable<T>): T
    function lastAsync<T>(iterable: AsyncIterable<T>): Promise<T>
    last([1, 2, 3]) // 3
    last([]) // throw RuntimeError

    match, matchAsync

    function match<T>(iterable: Iterable<T>, sequence: ArrayLike<T>): boolean
    function matchAsync<T>(iterable: AsyncIterable<T>, sequence: ArrayLike<T>): Promise<boolean>
    match([1, 2, 3], [2, 3]) // true
    match([1, 2, 3], [3, 2]) // false
    match([1, 2, 3], []) // true

    reduce, reduceAsync

    function reduce<T, U>(
      iterable: Iterable<T>
    , fn:
        ((accumulator: T, currentValue: T, index: number) => T)
      & ((accumulator: U, currentValue: T, index: number) => U)
    , initialValue?: U
    )
    function reduceAsync<T, U>(
      iterable: Iterable<T> | AsyncIterable<T>
    , fn:
        ((accumulator: T, currentValue: T, index: number) => T | PromiseLike<T>)
      & ((accumulator: U, currentValue: T, index: number) => U | PromiseLike<U>)
    , initialValue?: U
    )
    reduce([], (acc, cur) => acc + cur) // throw RuntimeError
    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: T, index: number) => unknown | PromiseLike<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<T[]>
    toArray([1, 2, 3]) // Array [1, 2, 3]

    toSet, toSetAsync

    function toSet<T>(iterable: Iterable<T>): Set<T>
    function toSetAsync<T>(iterable: AsyncIterable<T>): Promise<Set<T>>
    toSet([1, 1, 2, 2, 3, 3]) // Set [1, 2, 3]

    Install

    npm i iterable-operator

    DownloadsWeekly Downloads

    174

    Version

    0.13.6

    License

    MIT

    Unpacked Size

    28.5 MB

    Total Files

    1862

    Last publish

    Collaborators

    • avatar