streams
Version:
A lazy streams library for functional composition in JavaScript.
162 lines (161 loc) • 6.59 kB
TypeScript
/**
* 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 AsyncIteratorStream are a superset of the
* operations described in the
* [Async Iterator Helpers](https://github.com/tc39/proposal-async-iterator-helpers)
* proposal.
*
* The behavior of all operations here that correspond to operations in the
* `Async Iterator Helpers` proposal are defined (as best as possible) to match
* exactly with the behavior of the corresponding `Async Iterator Helpers`
* operations. This is intended to allow users of this library to seamlessly
* switch between this library and the `Async Iterator Helpers` once those are
* implemented and available.
*
* However, this library is NOT a polyfill for `Async Iterator Helpers`. To use
* this library, an async iterable iterator or generator needs to be explicitly
* wrapped in an AsyncIteratorStream like in this example:
*
* ```
* import "streams/asyncGenerator";
*
* async function* generator() {
* yield* [1, 2, 3];
* }
*
* generator() // returns an AsyncGenerator
* .stream() // convert to AsyncIteratorStream first!
* .forEach(console.log); // use the AsyncIteratorStream APIs
* ```
*/
export declare class AsyncIteratorStream<T> implements AsyncIterator<T, undefined, unknown> {
private readonly iterator;
/**
* Creates an AsyncIteratorStream from an Iterator or Iterable.
*
* ```
* AsyncIteratorStream.from([1, 2, 3]).map(x => x * 2).forEach(console.log);
* ```
*/
static from<T>(it: Iterable<T> | AsyncIterable<T> | AsyncIterator<T, unknown, undefined>): AsyncIteratorStream<T>;
readonly next: () => AsyncStreamResult<T>;
readonly return?: () => AsyncStreamResult<T>;
readonly throw?: (e?: unknown) => AsyncStreamResult<T>;
constructor(iterator: AsyncIterator<T, unknown, undefined>);
stream(): this;
[Symbol.asyncIterator](): this;
[Symbol.asyncDispose](): Promise<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): AsyncIteratorStream<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): AsyncIteratorStream<U>;
/**
* Like `map` but the result from each call to `transform` is awaited
* before producing the next transformed element.
*
* @param transform an async function to apply to each element of this stream
*/
mapAwait<U = T>(transform: (_: T) => Promise<U>): AsyncIteratorStream<U>;
/**
*
* See also [IteratorHelpers#flatMap](https://github.com/tc39/proposal-iterator-helpers#flatmapmapperfn).
*
* @param transform
*/
flatMap<U>(transform: (_: T) => AsyncIterable<U> | AsyncIterator<U, unknown, undefined>): AsyncIteratorStream<U>;
batch(batchSize: number): AsyncIteratorStream<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): AsyncIteratorStream<T>;
/**
*
* See also [IteratorHelpers#drop](https://github.com/tc39/proposal-iterator-helpers#droplimit).
*
* @param n
*/
drop(n: number): AsyncIteratorStream<T>;
dropWhile(predicate: (_: T) => boolean): AsyncIteratorStream<T>;
takeWhile(predicate: (_: T) => boolean): AsyncIteratorStream<T>;
peek(observer: (_: T) => void): AsyncIteratorStream<T>;
/**
*
* See also [IteratorHelpers#forEach](https://github.com/tc39/proposal-iterator-helpers#foreachfn).
*
* @param block
*/
forEach(block: (_: T) => unknown | Promise<unknown>): Promise<void>;
collect<A, R = A>(container: A, accumulator: (a: A, t: T) => void, finisher: (_: A) => R): Promise<R>;
collect<A>(container: A, accumulator: (a: A, t: T) => void): Promise<A>;
/**
*
* See also [IteratorHelpers#every](https://github.com/tc39/proposal-iterator-helpers#everyfn).
*
* @param predicate
*/
every(predicate: (_: T) => boolean): Promise<boolean>;
some(predicate: (_: T) => boolean): Promise<boolean>;
none(predicate: (_: T) => boolean): Promise<boolean>;
count(): Promise<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): Promise<T | undefined>;
first(predicate?: (_: T) => boolean): Promise<T | undefined>;
last(predicate?: (_: T) => boolean): Promise<T | undefined>;
max(comparator: (a: T, b: T) => number): Promise<T | undefined>;
min(comparator: (a: T, b: T) => number): Promise<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): Promise<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): Promise<R>;
fold(reducer: (a: T, b: T) => T): Promise<T | undefined>;
/**
* See also [IteratorHelpers#toArray](https://github.com/tc39/proposal-iterator-helpers#toarray).
*/
toArray(): Promise<T[]>;
}
type AsyncStreamResult<T> = Promise<IteratorResult<T, undefined>>;
export {};