streams/iterator-stream.d.ts

A lazy streams library for functional composition in JavaScript.

/**
 * An asynchronous stream that produces elements of type `T` on demand.
 *
 * This is an extension of the built-in `AsyncIterable<T>` protocol.
 *
 * The operations defined here in IteratorStream are a superset of the
 * operations described in the
 * [Iterator Helpers](https://github.com/tc39/proposal-iterator-helpers)
 * proposal.
 *
 * The behavior of all operations here that correspond to operations in the
 * `Iterator Helpers` proposal are defined (as best as possible) to match
 * exactly with the behavior of the corresponding `Iterator Helpers`
 * operations. This is intended to allow users of this library to seamlessly
 * switch between this library and the `Iterator Helpers` once those are
 * implemented and available.
 *
 * However, this library is NOT a polyfill for `Iterator Helpers`. To use
 * this library, an iterable iterator or generator needs to be explicitly
 * wrapped in an IteratorStream like in this example:
 *
 * ```
 * import "streams/sync";
 *
 * function* generator() {
 *   yield* [1, 2, 3];
 * }
 *
 * generator()               // returns an AsyncGenerator
 *   .stream()               // convert to IteratorStream first!
 *   .forEach(console.log);  // use the IteratorStream APIs
 * ```
 */
export declare class IteratorStream<T> implements Iterator<T, undefined, unknown> {
    private readonly iterator;
    /**
     * Creates an IteratorStream from a Iterator or Iterable.
     *
     * ```
     * IteratorStream.from([1, 2, 3]).map(x => x * 2).forEach(console.log);
     * ```
     */
    static from<T>(it: Iterable<T> | Iterator<T, unknown, undefined>): IteratorStream<T>;
    readonly next: () => IteratorResult<T, undefined>;
    readonly return?: () => IteratorResult<T, undefined>;
    readonly throw?: (e?: unknown) => IteratorResult<T, undefined>;
    constructor(iterator: Iterator<T, unknown, undefined>);
    stream(): this;
    [Symbol.iterator](): this;
    [Symbol.dispose](): void;
    /**
     * Returns a new stream that skips elements of this stream not matched by the
     * `predicate`.
     *
     * See also [IteratorHelpers#filter](https://github.com/tc39/proposal-iterator-helpers#filterfiltererfn).
     *
     * @param predicate a function that decides whether to include each element
     * in the new stream (true) or to exclude the element (false)
     */
    filter(predicate: (_: T) => boolean): IteratorStream<T>;
    /**
     * Returns a new stream that transforms each element of this stream
     * using the provided function.
     *
     * See also [IteratorHelpers#map](https://github.com/tc39/proposal-iterator-helpers#mapmapperfn).
     *
     * @param transform a function to apply to each element of this stream
     */
    map<U = T>(transform: (_: T) => U): IteratorStream<U>;
    /**
     *
     * See also [IteratorHelpers#flatMap](https://github.com/tc39/proposal-iterator-helpers#flatmapmapperfn).
     *
     * @param transform
     */
    flatMap<U>(transform: (_: T) => Iterable<U> | Iterator<U, unknown, undefined>): IteratorStream<U>;
    batch(batchSize: number): IteratorStream<T[]>;
    /**
     * Returns a new stream that produces up to the first `limit` number of
     * elements of this stream.
     *
     * See also [IteratorHelpers#take](https://github.com/tc39/proposal-iterator-helpers#takelimit).
     *
     * @param limit the maximum number of items to produce
     */
    take(limit: number): IteratorStream<T>;
    /**
     *
     * See also [IteratorHelpers#drop](https://github.com/tc39/proposal-iterator-helpers#droplimit).
     *
     * @param n
     */
    drop(n: number): IteratorStream<T>;
    dropWhile(predicate: (_: T) => boolean): IteratorStream<T>;
    takeWhile(predicate: (_: T) => boolean): IteratorStream<T>;
    peek(observer: (_: T) => void): IteratorStream<T>;
    /**
     *
     * See also [IteratorHelpers#forEach](https://github.com/tc39/proposal-iterator-helpers#foreachfn).
     *
     * @param block
     */
    forEach(block: (_: T) => unknown): void;
    collect<A, R = A>(container: A, accumulator: (a: A, t: T) => void, finisher: (_: A) => R): R;
    collect<A>(container: A, accumulator: (a: A, t: T) => void): A;
    /**
     *
     * See also [IteratorHelpers#every](https://github.com/tc39/proposal-iterator-helpers#everyfn).
     *
     * @param predicate
     */
    every(predicate: (_: T) => boolean): boolean;
    /**
     * See also [IteratorHelpers#some](https://github.com/tc39/proposal-iterator-helpers#somefn).
     *
     * @param predicate
     */
    some(predicate: (_: T) => boolean): boolean;
    none(predicate: (_: T) => boolean): boolean;
    count(): number;
    /**
     * Returns the first element that matches the predicate.
     *
     * This is the same as the {@link first()} method except that the predicate is
     * required and a `TypeError` will be thrown if a predicate is not supplied.
     *
     * See also [IteratorHelpers#find](https://github.com/tc39/proposal-iterator-helpers#findfn).
     *
     * @param predicate
     */
    find(predicate: (_: T) => boolean): T | undefined;
    first(predicate?: (_: T) => boolean): T | undefined;
    last(predicate?: (_: T) => boolean): T | undefined;
    max(comparator: (a: T, b: T) => number): T | undefined;
    min(comparator: (a: T, b: T) => number): T | undefined;
    /**
     *
     * See also [IteratorHelpers#reduce](https://github.com/tc39/proposal-iterator-helpers#reducereducer--initialvalue-).
     *
     * @param reducer
     * @param initial
     */
    reduce<R = T>(reducer: (a: R, b: T) => R, initial?: R): R;
    /**
     * Like {@link reduce()} but returns `undefined` if this stream is empty
     * instead of throwing `TypeError`.
     *
     * @param reducer
     * @param initial
     */
    fold<R = T>(reducer: (a: R, b: T) => R, initial: R): R | undefined;
    fold(reducer: (a: T, b: T) => T): T | undefined;
    /**
     * See also [IteratorHelpers#toArray](https://github.com/tc39/proposal-iterator-helpers#toarray).
     */
    toArray(): T[];
}