@jderrington/lazy-iterable
Options
All
  • Public
  • Public/Protected
  • All
Menu
author

James Errington james.errington@protonmail.com

since

1.0.0

A wrapper class that encapsulates a lazyily-evaluated iterable, where each value can be generated by some async action. Note that while the actions individually can be async i.e. not guaranteed to return immediately, they are generated in serial; when iterating a AsyncLazyIterable, the first element must be generated before the second can start. This is not always the preferred behaviour, and it may be the case that methods such as Promise.all are more suited in some use cases, when async actions can be run in parallel.

Type parameters

Hierarchy

  • AsyncLazyIterable

Index

Constructors

Lazy Methods

Eager Methods

Conversion Methods

Constructors

constructor

  • new AsyncLazyIterable<T>(generator: AsyncGenerator<T, any, unknown>): AsyncLazyIterable<T>
  • example

    Create a new AsyncLazyIterable from an async generator function:

    async function* generator() {
  for (let i = 0; i < 10; i++) {
    yield i
  }
}

const iterable = new AsyncLazyIterable(generator())
    since

    1.0.0

    Type parameters

    • T

    Parameters

    • generator: AsyncGenerator<T, any, unknown>

      The generator to be wrapped in the AsyncLazyIterable

    Returns AsyncLazyIterable<T>

Lazy Methods

drop

dropWhile

  • Returns a new AsyncLazyIterable that ignores values from the base generator until the provided predicate is false.

    see

    LazyIterable.dropWhile for more information

    see

    LearnRxJS - skipWhile for the RxJS version

    since

    1.0.0

    Parameters

    • predicate: (value: T, index: number) => boolean
        • (value: T, index: number): boolean

        • Parameters

          • value: T
          • index: number

          Returns boolean

    Returns AsyncLazyIterable<T>

    A new AsyncLazyIterable, for chaining

feedTo

  • feedTo<S>(generatorFunc: (seed: AsyncIterable<T>) => AsyncGenerator<S, any, unknown>): AsyncLazyIterable<S>

  • Returns a new AsyncLazyIterable that yields the values returned from calling the provided generator with values from the base generator. Can be considered a generalisation of the other lazy processing methods, and is useful when more complex processing is required; for example, when stateful knowledge of past values is needed.

    see

    LazyIterable.feedTo for more information

    since

    1.0.0

    Type parameters

    • S

    Parameters

    • generatorFunc: (seed: AsyncIterable<T>) => AsyncGenerator<S, any, unknown>
        • (seed: AsyncIterable<T>): AsyncGenerator<S, any, unknown>

        • Parameters

          • seed: AsyncIterable<T>

          Returns AsyncGenerator<S, any, unknown>

    Returns AsyncLazyIterable<S>

    A new AsyncLazyIterable, for chaining

filter

map

  • Returns a new AsyncLazyIterable that yields the result of applying the provided callback to values from the base generator.

    see

    LazyIterable.map for more information

    see

    MDN - Array.prototype.map() for the standard Array method.

    since

    1.0.0

    Type parameters

    • S

      The type returned by the callback

    Parameters

    • callback: (value: T, index: number) => S
        • (value: T, index: number): S

        • Parameters

          • value: T
          • index: number

          Returns S

    Returns AsyncLazyIterable<S>

    A new AsyncLazyIterable, for chaining

runEffect

  • Performs an effectful callback effect for each value yielded from the base generator, and returns a new AsyncLazyIterable that just passes the values on. Can be considered a helper function for an effectful map on the identity function, or a lazy version of forEach.

    see

    LazyIterable.runEffect for more information

    since

    1.0.0

    Parameters

    • effect: (value: T, index: number) => unknown
        • (value: T, index: number): unknown

        • Parameters

          • value: T
          • index: number

          Returns unknown

    Returns AsyncLazyIterable<T>

    A new AsyncLazyIterable, for chaining

take

takeWhile

  • Returns a new AsyncLazyIterable that yields values from the base generator until the provided predicate is false. This is different to filter in that no values after the first false response are yielded.

    see

    LazyIterable.takeWhile for more information

    see

    LearnRxJS - takeWhile for the RxJS version

    since

    1.0.0

    Parameters

    • predicate: (value: T, index: number) => boolean
        • (value: T, index: number): boolean

        • Parameters

          • value: T
          • index: number

          Returns boolean

    Returns AsyncLazyIterable<T>

    A new AsyncLazyIterable, for chaining

Eager Methods

every

  • every(predicate: (value: T, index: number) => boolean): Promise<boolean>

  • Tests values yielded from the AsyncLazyIterable against the given predicate, returning true if it is satisfied every time. As an eager method, calling every will trigger an evaluation of the AsyncLazyIterable. Since values cannot be re-yielded once run, it may be more appropriate to use the standard Array method for some use cases.

    see

    LazyIterable.every for more information

    see

    MDN - Array.prototype.every() for the standard Array method.

    since

    1.0.0

    Parameters

    • predicate: (value: T, index: number) => boolean
        • (value: T, index: number): boolean

        • Parameters

          • value: T
          • index: number

          Returns boolean

    Returns Promise<boolean>

    A Promise that resolves to true if every value satisfies the given predicate, else false.

find

  • find(predicate: (value: T, index: number) => boolean): Promise<undefined | T>

  • Returns the first value yielded by the AsyncLazyIterable that satisfies the given predicate. As an eager method, calling find will trigger an evaluation of the AsyncLazyIterable. Since values cannot be re-yielded once run, it may be more appropriate to use the standard Array method for some use cases.

    see

    LazyIterable.find for more information

    see

    MDN - Array.prototype.find() for the standard Array method.

    since

    1.0.0

    Parameters

    • predicate: (value: T, index: number) => boolean
        • (value: T, index: number): boolean

        • Parameters

          • value: T
          • index: number

          Returns boolean

    Returns Promise<undefined | T>

    A Promise that resolves to the value of the first element that satisfies the given predicate, or undefined if no value exists.

forEach

  • forEach(callback: (value: T, index: number) => void): Promise<void>

  • Similar to runEffect, calls the given callback for each value yielded from the AsyncLazyIterable, but does not return a new iterable. As an eager method, calling forEach will trigger an evaluation of the AsyncLazyIterable. Since values cannot be re-yielded once run, it may be more appropriate to use the standard Array method for some use cases.

    see

    LazyIterable.forEach for more information

    see

    MDN - Array.prototype.forEach() for the standard Array method.

    since

    1.0.0

    Parameters

    • callback: (value: T, index: number) => void
        • (value: T, index: number): void

        • Parameters

          • value: T
          • index: number

          Returns void

    Returns Promise<void>

includes

  • includes(search: T): Promise<boolean>

  • Determines if the AsyncLazyIterable yielded a given value search. As an eager method, calling includes will trigger an evaluation of the AsyncLazyIterable. Since values cannot be re-yielded once run, it may be more appropriate to use the standard Array method for some use cases.

    see

    LazyIterable.includes for more information

    see

    MDN - Array.prototype.includes() for the standard Array method.

    since

    1.0.0

    Parameters

    • search: T

      The value to search for.

    Returns Promise<boolean>

    A Promise that resolves to true if the given value was yielded, else false.

indexOf

  • indexOf(search: T): Promise<number>

  • Returns the index of the value that matches the given search value; in a AsyncLazyIterable, this translates to the number of values that have been yielded before an instance of search is found. As an eager method, calling indexOf will trigger an evaluation of the AsyncLazyIterable. Since values cannot be re-yielded once run, it may be more appropriate to use the standard Array method for some use cases.

    see

    LazyIterable.indexOf for more information

    see

    MDN - Array.prototype.indexOf() for the standard Array method.

    since

    1.0.0

    Parameters

    • search: T

      The value to search for.

    Returns Promise<number>

    A Promise that resolves to how many values had been yielded from the AsyncLazyIterable before search, or -1 if search is never yielded.

lastIndexOf

  • lastIndexOf(search: T): Promise<number>

  • Returns the last index of the value that matches the given search value; in a AsyncLazyIterable, this translates to the number of values that have been yielded before the last instance of search is found. As an eager method, calling lastIndexOf will trigger an evaluation of the AsyncLazyIterable. Since values cannot be re-yielded once run, it may be more appropriate to use the standard Array method for some use cases. The AsyncLazyIterable must also be finite for this method to work.

    Note the difference between this method and the standard Array implementation; because a AsyncLazyIterable encapsulates a stream of values that have yet to be fully evaluated, lastIndexOf cannot search backwards, and so this method on its own is likely much less efficient.

    see

    LazyIterable.lastIndexOf for more information

    see

    MDN - Array.prototype.lastIndexOf() for the standard Array method.

    since

    1.0.0

    Parameters

    • search: T

      The value to search for.

    Returns Promise<number>

    A Promise that resolves to how many values had been yielded from the AsyncLazyIterable before the last instance of search, or -1 if search is never yielded.

next

  • next(): Promise<IteratorResult<T, any>>

  • Returns a Promise to an object with two properties: value, and done. value holds the next value of the iteration sequence, based on the current state of the internal generator. done is true if the last value of the generator has already been consumed, otherwise false.

    example

    Using the next method to manually iterate a AsyncLazyIterable

    async function* asyncGenerator() { yield* [1, 2, 3] }

const iterable = new AsyncLazyIterable(asyncGenerator())
await iterable.next() // Returns { value: 1, done: false }
await iterable.next() // Returns { value: 2, done: false }
await iterable.next() // Returns { value: 3, done: false }
await iterable.next() // Returns { value: undefined, done: true }
// All subsequent calls to next() return { value: undefined, done: true }
    see

    MDN - Iterators and generators for more detail

    since

    1.0.0

    Returns Promise<IteratorResult<T, any>>

    The result from one iteration of the generator

reduce

  • reduce<S>(reducer: (accumulator: S, value: T, index: number) => S, initial: S): Promise<S>

  • Applies the given reducer function for each value yielded from the AsyncLazyIterable, returning a single output value. As an eager method, calling reduce will trigger an evaluation of the AsyncLazyIterable. Since values cannot be re-yielded once run, it may be more appropriate to use the standard Array method for some use cases.

    see

    LazyIterable.reduce for more information

    see

    MDN - Array.prototype.reduce() for the standard Array method.

    since

    1.0.0

    Type parameters

    • S

      The type of the accumulated value

    Parameters

    • reducer: (accumulator: S, value: T, index: number) => S

      The function to apply for each value yielded

        • (accumulator: S, value: T, index: number): S

        • Parameters

          • accumulator: S
          • value: T
          • index: number

          Returns S

    • initial: S

      The initial value for the accumulator

    Returns Promise<S>

    A Promise that resolves to the final result of the reduction

some

  • some(predicate: (value: T, index: number) => boolean): Promise<boolean>

  • Tests values yielded from the AsyncLazyIterable against the given predicate, returning true if it is satisfied at least once. As an eager method, calling some will trigger an evaluation of the AsyncLazyIterable. Since values cannot be re-yielded once run, it may be more appropriate to use the standard Array method for some use cases.

    see

    LazyIterable.some for more information

    see

    MDN - Array.prototype.some() for the standard Array method.

    since

    1.0.0

    Parameters

    • predicate: (value: T, index: number) => boolean
        • (value: T, index: number): boolean

        • Parameters

          • value: T
          • index: number

          Returns boolean

    Returns Promise<boolean>

    A Promise that resolves to true if at least one value satisfies the given predicate, else false.

Conversion Methods

toArray

  • toArray(): Promise<T[]>

  • Returns a standard Array containing the values yielded from the AsyncLazyIterable in order. This triggers a full evaluation of the AsyncLazyIterable, resolving each value in serial and building an Array; thus, the Promise returned from this method will not resolve until value has been resolved. It also means that the AsyncLazyIterable must not be infinite.

    example

    Convert an AsyncLazyIterable to an Array

    async function* generator() { yield* ["A", "B", "C", "D"] }
const asyncIterable = new AsyncLazyIterable(generator())
const array = await asyncIterable.toArray()
    see

    MDN - Array.reverse() for the standard Array method.

    since

    1.0.0

    Returns Promise<T[]>

    A new Array instance

toSynchronousIterable

Static fromIterable

  • Converts an AsyncIterable into a new AsyncLazyIterable. The input can be anything that implements the @@asyncIterator method. To create a AsyncLazyIterable from an AsyncGenerator, the standard constructor function can be used.

    example

    Convert a custom AsyncIterable into a AsyncLazyIterable

    const customIterable = {
  async* [Symbol.iterator]() {
    yield 1
    yield 2
  }
}
const lazyIterable = AsyncLazyIterable.fromIterable(customIterable)
    see

    MDN - Iterators and generators for more detail

    since

    1.0.0

    Type parameters

    • S

      The type returned from the input iterable

    Parameters

    • iterable: AsyncIterable<S>

    Returns AsyncLazyIterable<S>

    A new AsyncLazyIterable

Legend

  • Method

Generated using TypeDoc